{"info":{"title":"ServiceBox — Cities API","version":"1.0.0","description":"About 171,000 cities and towns worldwide with population, timezone and coordinates, and nearest-city search; second-level districts worldwide; and Turkey's postal codes with their neighbourhoods and villages. Places in Turkey carry their Turkish names. Collections answer `{ items, next_cursor, total }`; page with `limit` (1–200, default 50) and `cursor` (pass back `next_cursor` with the same filters). Errors are RFC 9457 problems. Every answer has an ETag: send it back in `If-None-Match` for a `304` while the data is unchanged.\n\nData: GeoNames (geonames.org), licensed under CC BY 4.0, including GeoNames postal codes. Turkish country and currency names: Unicode CLDR."},"paths":{"/v1/cities/cities":{"get":{"summary":"List cities","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/City"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null on the last page."}}}}},"headers":{"ETag":{"schema":{"type":"string"}}},"description":"A page of cities."},"304":{"description":"Not modified."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Invalid parameters."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"in":"query","name":"country","schema":{"type":"string"},"required":false,"description":"ISO 3166-1 alpha-2 code."},{"in":"query","name":"subdivision","schema":{"type":"string"},"required":false,"description":"Subdivision id, e.g. TR.34."},{"in":"query","name":"q","schema":{"type":"string"},"required":false,"description":"Name search."},{"in":"query","name":"minPopulation","schema":{"type":"integer","minimum":0},"required":false,"description":"Minimum population."},{"in":"query","name":"sort","schema":{"enum":["population","name"],"type":"string"},"required":false,"description":"`population` (default, largest first) or `name`."},{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200,"minimum":1},"required":false,"description":"Items per page, 1–200."},{"in":"query","name":"cursor","schema":{"type":"string"},"required":false,"description":"The `next_cursor` of the previous page, with the same filters."},{"in":"header","name":"If-None-Match","schema":{"type":"string"},"required":false,"description":"An ETag from a previous answer; 304 while unchanged."}],"description":"Cities and towns with at least 1,000 inhabitants (about 171,000 worldwide), largest first unless `sort=name`. Filter by country, subdivision, a name search (start of a word, case- and accent-insensitive: `kadikoy` finds Kadıköy) and a minimum population. Turkish places carry their Turkish names.","operationId":"listCities","x-sbx-credits":1}},"/v1/cities/districts":{"get":{"summary":"List districts","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/District"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null on the last page."}}}}},"headers":{"ETag":{"schema":{"type":"string"}}},"description":"A page of districts."},"304":{"description":"Not modified."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Invalid parameters."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"in":"query","name":"subdivision","schema":{"type":"string"},"required":false,"description":"Subdivision id, e.g. TR.34."},{"in":"query","name":"country","schema":{"type":"string"},"required":false,"description":"ISO 3166-1 alpha-2 code."},{"in":"query","name":"q","schema":{"type":"string"},"required":false,"description":"Name search."},{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200,"minimum":1},"required":false,"description":"Items per page, 1–200."},{"in":"query","name":"cursor","schema":{"type":"string"},"required":false,"description":"The `next_cursor` of the previous page, with the same filters."},{"in":"header","name":"If-None-Match","schema":{"type":"string"},"required":false,"description":"An ETag from a previous answer; 304 while unchanged."}],"description":"Second-level administrative divisions: Turkey's 974 districts (ilçe) with their Turkish names, counties and similar elsewhere. Give `subdivision` (the districts of one province) or `country`. Sorted by name.","operationId":"listDistricts","x-sbx-credits":1}},"/v1/cities/timezones":{"get":{"summary":"List timezones","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor","total"],"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Timezone"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null on the last page."}}}}},"headers":{"ETag":{"schema":{"type":"string"}}},"description":"The timezones."},"304":{"description":"Not modified."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"in":"header","name":"If-None-Match","schema":{"type":"string"},"required":false,"description":"An ETag from a previous answer; 304 while unchanged."}],"description":"Every IANA timezone the cities use, with its city count, sorted by name. Free. Not paged: the whole list in one answer.","operationId":"listTimezones","x-sbx-credits":0}},"/v1/cities/cities/{id}":{"get":{"summary":"Get a city","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/City"}}},"headers":{"ETag":{"schema":{"type":"string"}}},"description":"The city."},"304":{"description":"Not modified."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"404":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Not found."},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"in":"path","name":"id","schema":{"type":"string"},"required":true},{"in":"header","name":"If-None-Match","schema":{"type":"string"},"required":false,"description":"An ETag from a previous answer; 304 while unchanged."}],"description":"One city by its id.","operationId":"getCity","x-sbx-credits":1}},"/v1/cities/postal-codes":{"get":{"summary":"List postal codes","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor","total","meta"],"properties":{"meta":{"type":"object","properties":{"country":{"type":"string"}}},"items":{"type":"array","items":{"$ref":"#/components/schemas/PostalPlace"}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null on the last page."}}}}},"headers":{"ETag":{"schema":{"type":"string"}}},"description":"A page of postal-code places."},"304":{"description":"Not modified."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Invalid parameters."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"in":"query","name":"country","schema":{"type":"string"},"required":true,"description":"ISO 3166-1 alpha-2 code; TR."},{"in":"query","name":"code","schema":{"type":"string"},"required":false,"description":"A postal code, e.g. 34710."},{"in":"query","name":"district","schema":{"type":"string"},"required":false,"description":"District id, e.g. TR.34.7732454."},{"in":"query","name":"subdivision","schema":{"type":"string"},"required":false,"description":"Subdivision id, e.g. TR.34."},{"in":"query","name":"q","schema":{"type":"string"},"required":false,"description":"Place name search."},{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200,"minimum":1},"required":false,"description":"Items per page, 1–200."},{"in":"query","name":"cursor","schema":{"type":"string"},"required":false,"description":"The `next_cursor` of the previous page, with the same filters."},{"in":"header","name":"If-None-Match","schema":{"type":"string"},"required":false,"description":"An ETag from a previous answer; 304 while unchanged."}],"description":"Postal codes with the places they serve: for Turkey, about 36,000 neighbourhoods (mahalle) and villages, each with its district and province. Filter by `code`, `district`, `subdivision` or a name search. `country` is required; available for TR.","operationId":"listPostalCodes","x-sbx-credits":1}},"/v1/cities/cities/nearby":{"get":{"summary":"List cities near a point","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","required":["items","next_cursor","total","meta"],"properties":{"meta":{"type":"object","properties":{"center":{"$ref":"#/components/schemas/Location"},"radiusKm":{"type":"number"}}},"items":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/City"},{"type":"object","required":["distanceKm"],"properties":{"distanceKm":{"type":"number"}}}]}},"total":{"type":"integer"},"next_cursor":{"type":["string","null"],"description":"Pass back as `cursor` for the next page; null on the last page."}}}}},"headers":{"ETag":{"schema":{"type":"string"}}},"description":"A page of nearby cities."},"304":{"description":"Not modified."},"400":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Invalid parameters."},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/PaymentRequired"},"429":{"$ref":"#/components/responses/TooManyRequests"},"502":{"$ref":"#/components/responses/BadGateway"},"504":{"$ref":"#/components/responses/GatewayTimeout"}},"parameters":[{"in":"query","name":"lat","schema":{"type":"number","maximum":90,"minimum":-90},"required":true,"description":"Latitude (WGS84)."},{"in":"query","name":"lon","schema":{"type":"number","maximum":180,"minimum":-180},"required":true,"description":"Longitude (WGS84)."},{"in":"query","name":"radiusKm","schema":{"type":"number","default":25,"maximum":200,"minimum":0.1},"required":false,"description":"Search radius, 0.1–200 km."},{"in":"query","name":"minPopulation","schema":{"type":"integer","minimum":0},"required":false,"description":"Minimum population."},{"in":"query","name":"limit","schema":{"type":"integer","default":50,"maximum":200,"minimum":1},"required":false,"description":"Items per page, 1–200."},{"in":"query","name":"cursor","schema":{"type":"string"},"required":false,"description":"The `next_cursor` of the previous page, with the same filters."},{"in":"header","name":"If-None-Match","schema":{"type":"string"},"required":false,"description":"An ETag from a previous answer; 304 while unchanged."}],"description":"Cities within `radiusKm` of a point, nearest first, each with `distanceKm`. Pages through at most the 500 nearest.","operationId":"listNearbyCities","x-sbx-credits":1}}},"openapi":"3.1.0","servers":[{"url":"https://api.servicebox.io"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"components":{"schemas":{"City":{"type":"object","required":["id","name","asciiName","countryCode","subdivision","population","timezone","elevation","location","isCapital"],"properties":{"id":{"type":"string","examples":["745044"],"description":"GeoNames id."},"name":{"type":"string","examples":["İstanbul"]},"location":{"$ref":"#/components/schemas/Location"},"timezone":{"type":["string","null"],"examples":["Europe/Istanbul"]},"asciiName":{"type":"string","examples":["Istanbul"]},"elevation":{"type":["integer","null"],"description":"Metres."},"isCapital":{"type":"boolean"},"population":{"type":"integer"},"countryCode":{"type":"string","examples":["TR"]},"subdivision":{"type":["object","null"],"required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"Country":{"type":"object","required":["code","iso3","isoNumeric","name","nameTr","flag","continent","population","languages","neighbours","subdivisionCount"],"properties":{"tld":{"type":["string","null"],"examples":[".tr"]},"code":{"type":"string","examples":["TR"],"description":"ISO 3166-1 alpha-2."},"flag":{"type":"string","examples":["🇹🇷"]},"iso3":{"type":"string","examples":["TUR"]},"name":{"type":"string","examples":["Turkey"],"description":"English name."},"nameTr":{"type":"string","examples":["Türkiye"],"description":"Turkish name."},"areaKm2":{"type":["number","null"]},"capital":{"type":["string","null"],"examples":["Ankara"]},"currency":{"type":["object","null"],"required":["code","name","nameTr"],"properties":{"code":{"type":"string","examples":["TRY"]},"name":{"type":["string","null"]},"nameTr":{"type":["string","null"]}}},"continent":{"type":"object","required":["code","name"],"properties":{"code":{"enum":["AF","AN","AS","EU","NA","OC","SA"],"type":"string"},"name":{"type":"string"}}},"languages":{"type":"array","items":{"type":"string"},"examples":[["tr-TR","ku","diq","az","av"]]},"isoNumeric":{"type":"string","examples":["792"]},"neighbours":{"type":"array","items":{"type":"string"},"description":"ISO 3166-1 alpha-2 codes of bordering countries."},"population":{"type":"integer"},"phonePrefix":{"type":["string","null"],"examples":["+90"]},"postalCodeFormat":{"type":["string","null"],"examples":["#####"]},"subdivisionCount":{"type":"integer"}}},"Problem":{"type":"object","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"},"status":{"type":"integer"}}},"Coverage":{"type":"object","required":["dataVersion","places","ipAddresses"],"properties":{"places":{"type":"object","required":["source","licence","postalCodeCountries"],"properties":{"source":{"type":"string"},"licence":{"type":"string"},"postalCodeCountries":{"type":"array","items":{"type":"string"}}}},"dataVersion":{"type":"string","examples":["20260927"],"description":"The data snapshot, `YYYYMMDD`."},"ipAddresses":{"type":"object","required":["source","licence","level"],"properties":{"level":{"enum":["country"],"type":"string"},"source":{"type":"string"},"licence":{"type":"string"}}}}},"District":{"type":"object","required":["id","name","asciiName","countryCode","subdivision"],"properties":{"id":{"type":"string","examples":["TR.34.7732454"],"description":"Stable id, `<country>.<subdivision code>.<GeoNames id>`."},"name":{"type":"string","examples":["Avcılar"]},"asciiName":{"type":"string","examples":["Avcilar"]},"countryCode":{"type":"string","examples":["TR"]},"subdivision":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"IpLookup":{"type":"object","required":["ip","version","country"],"properties":{"ip":{"type":"string","examples":["88.255.1.1"],"description":"The address, normalized (IPv4-mapped IPv6 as IPv4, IPv6 compressed)."},"country":{"type":["object","null"],"required":["code","name","nameTr"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"nameTr":{"type":"string"}},"description":"Null for reserved, private or unassigned addresses."},"version":{"enum":[4,6],"type":"integer"}}},"Location":{"type":"object","required":["lat","lon"],"properties":{"lat":{"type":"number"},"lon":{"type":"number"}}},"Timezone":{"type":"object","required":["id","cityCount"],"properties":{"id":{"type":"string","examples":["Europe/Istanbul"],"description":"IANA timezone name."},"cityCount":{"type":"integer"}}},"Continent":{"type":"object","required":["code","name","countryCount"],"properties":{"code":{"enum":["AF","AN","AS","EU","NA","OC","SA"],"type":"string"},"name":{"type":"string"},"countryCount":{"type":"integer"}}},"PlaceLookup":{"type":"object","required":["location","country","subdivision","district","postalCode","nearestCity"],"properties":{"country":{"type":["object","null"],"required":["code","name","nameTr"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"nameTr":{"type":"string"}},"description":"The nearest city's country; null when no city of 1,000+ inhabitants is within 100 km."},"district":{"type":["object","null"],"required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}},"description":"The nearest located postal place's district (Turkey), within 5 km."},"location":{"$ref":"#/components/schemas/Location"},"postalCode":{"type":["object","null"],"required":["postalCode","name","distanceKm"],"properties":{"name":{"type":"string"},"distanceKm":{"type":"number"},"postalCode":{"type":"string"}}},"nearestCity":{"type":["object","null"],"required":["id","name","population","distanceKm"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"distanceKm":{"type":"number"},"population":{"type":"integer"}}},"subdivision":{"type":["object","null"],"required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"PostalPlace":{"type":"object","required":["postalCode","name","countryCode","district","subdivision","location"],"properties":{"name":{"type":"string","examples":["Firuzköy"],"description":"The place the code serves; in Turkey a neighbourhood (mahalle) or village. Spelled as the postal source publishes it, which often writes ı as i."},"district":{"type":["object","null"],"required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}},"location":{"anyOf":[{"$ref":"#/components/schemas/Location"},{"type":"null"}],"description":"The place's own point; null when the source only locates the district."},"postalCode":{"type":"string","examples":["34310"]},"countryCode":{"type":"string","examples":["TR"]},"subdivision":{"type":["object","null"],"required":["id","name"],"properties":{"id":{"type":"string"},"name":{"type":"string"}}}}},"Subdivision":{"type":"object","required":["id","code","countryCode","name","asciiName"],"properties":{"id":{"type":"string","examples":["TR.34"],"description":"Stable id, `<country>.<code>`. Not an ISO 3166-2 code."},"code":{"type":"string","examples":["34"]},"name":{"type":"string","examples":["İstanbul"]},"asciiName":{"type":"string","examples":["Istanbul"]},"countryCode":{"type":"string","examples":["TR"]}}}},"responses":{"BadGateway":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"examples":{"upstream_auth":{"value":{"type":"https://servicebox.io/problems/upstream_auth","title":"Bad Gateway","detail":"The upstream refused ServiceBox's credential","status":502}},"upstream_error":{"value":{"type":"https://servicebox.io/problems/upstream_error","title":"Bad Gateway","detail":"The upstream failed (500)","status":502}}}}},"description":"`upstream_error`: the data source failed. `upstream_auth`: the data source refused ServiceBox's own credential; not your key."},"Unauthorized":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://servicebox.io/problems/unauthorized","title":"Unauthorized","detail":"Missing or invalid API key/bearer token","status":401}}},"description":"Missing or invalid credentials."},"GatewayTimeout":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://servicebox.io/problems/upstream_timeout","title":"Gateway Timeout","detail":"Upstream request timed out","status":504}}},"description":"The data source timed out."},"PaymentRequired":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://servicebox.io/problems/payment_required","title":"Payment Required","detail":"Insufficient credits for this request","status":402}}},"description":"Insufficient credits."},"TooManyRequests":{"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"},"example":{"type":"https://servicebox.io/problems/rate_limited","title":"Too Many Requests","detail":"Rate limit exceeded, retry after backing off","status":429}}},"description":"Rate limit exceeded."}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"},"apiKeyQuery":{"in":"query","name":"apikey","type":"apiKey"}}}}