Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.byteful.com/llms.txt

Use this file to discover all available pages before exploring further.

The City object represents a geographic city in the Byteful system. It contains essential information about a city including its name, location coordinates, timezone, and relationships to larger geographic divisions like countries and subdivisions. The City object is fundamental to the geographic targeting capabilities of proxies, especially for residential proxy services.

​
Key Attributes

AttributeTypeDescription
city_idintegerUnique identifier for the city
city_namestringFull name of the city (e.g., “Paris”)
city_aliasstringHuman-friendly unique identifier for the city (e.g., “city_of_lights”)
city_latitudenumberLatitude coordinates of the city
city_longitudenumberLongitude coordinates of the city
city_timezonestringTimezone of the city (e.g., “Europe/Paris”)
city_populationintegerPopulation of the city
city_is_populousbooleanIndicates if the city is among the populous cities in its region
city_example_postcodestringExample postal/zip code for the city
subdivision_idstringID of the subdivision (state/province) where the city is located

​
Object Relationships

The City object is connected to several other objects in the Byteful API:
  • Subdivision: Each city belongs to a subdivision (state, province, region)
  • Country: Through the subdivision hierarchy, cities are associated with countries
  • Continent: Through the country hierarchy, cities are associated with continents
  • Proxies: Proxies can be geo-located in specific cities
  • Residential Proxies: Residential proxy generation can target specific cities
  • Mobile Proxies: Mobile proxy generation can target specific cities
EndpointDescription
GET /public/user/city/retrieve/{city_id}Retrieve a specific city by ID
GET /public/user/city/searchSearch cities using various filters
GET /public/user/residential/list?city_alias={city_alias}Generate residential proxies for a specific city
GET /public/user/mobile/list?city_alias={city_alias}Generate mobile proxies for a specific city

​
Example Response

{
  "data": {
    "city_id": 379657,
    "city_name": "Paris",
    "city_alias": "city_of_lights",
    "city_example_postcode": "75004",
    "city_is_populous": true,
    "city_latitude": 48.85341,
    "city_longitude": 2.3488,
    "city_timezone": "Europe/Paris",
    "city_population": 2138551,
    "subdivision_id": "fr-idf"
  },
  "message": "City successfully retrieved."
}

​
Usage Notes

  • The city_alias is particularly important for residential/mobile proxy targeting
  • The city_is_populous flag indicates cities that are among the top ten largest in their timezone with at least 300,000 population
  • Geographic targeting by city provides the most granular level of geographic control for proxy selection
  • Not all cities are available for residential/mobile proxy targeting - generally only those with city_is_populous set to true
  • The city_timezone attribute is useful for time-sensitive operations that need to account for local time
  • When searching for cities, you can filter by country using the country_id parameter or by subdivision using the subdivision_id parameter
  • The combination of city latitude and longitude can be used for geolocation services and mapping integrations