{"openapi":"3.1.0","info":{"title":"ForLab Geo API","version":"1.0.0","description":"Countries, administrative units, their boundaries, phone numbers, timezones, nearby places and postal codes from one versioned dataset. Turkey's level 3 is the official TÜİK mahalle and köy list (list_coverage complete); its boundaries are partial, as meta.coverage.neighborhood=partial and levels[].boundary_count say. Unless an operation permits anonymous access, /v1 calls need `Authorization: Bearer <key>`. Responses are `{data, meta}`; errors are `{status: failed, code}`. Data © OpenStreetMap contributors, Overture Maps Foundation (ODbL 1.0, https://opendatacommons.org/licenses/odbl/1-0/); timezone-boundary-builder (ODbL 1.0, same licence); GeoNames (CC BY 4.0, https://creativecommons.org/licenses/by/4.0/); CLDR (Unicode License v3, https://www.unicode.org/license.txt); tzdata (public domain); libphonenumber (Apache-2.0). Every response carries the full credit in meta.attribution."},"security":[{"bearer":[]}],"paths":{"/health":{"get":{"summary":"Readiness: 200 once a dataset is loaded, 503 NOT_READY before","security":[],"responses":{"200":{"description":"ok"},"503":{"$ref":"#/components/responses/Error"}}}},"/openapi.json":{"get":{"summary":"This document","security":[],"responses":{"200":{"description":"ok"}}}},"/v1/meta":{"get":{"x-worker-keyless":true,"summary":"Dataset version, public tileset URLs, sources and licences","responses":{"200":{"$ref":"#/components/responses/Ok"},"401":{"$ref":"#/components/responses/Error"}}}},"/v1/countries":{"get":{"x-worker-keyless":true,"summary":"All countries and dependencies with their profile","parameters":[{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"$ref":"#/components/responses/Ok"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"}}}},"/v1/countries/{cc}":{"get":{"x-worker-keyless":true,"summary":"One country: names, calling codes, currencies, languages, timezones, levels with coverage","parameters":[{"name":"cc","example":"TR","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"$ref":"#/components/responses/Ok"},"404":{"$ref":"#/components/responses/Error"}}}},"/v1/places":{"get":{"x-worker-keyless":true,"summary":"Children of a place (`parent`) or a name prefix search (`q`); exactly one of the two","parameters":[{"name":"parent","example":"TR-35","in":"query","schema":{"type":"string"},"description":"Country, region (il), county (ilçe) ID. An ilçe lists its official mahalle and köy (TÜİK); places off that list are not children."},{"name":"q","in":"query","schema":{"type":"string","maxLength":100},"description":"Name prefix (e.g. kuşa); case, diacritics and Turkish i/ı are ignored"},{"name":"country","in":"query","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"description":"Only with q, e.g. TR"},{"$ref":"#/components/parameters/lang"},{"name":"limit","example":10,"in":"query","schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Default 1000 for parent, 20 (max 100) for q"},{"name":"offset","example":0,"in":"query","schema":{"type":"integer","minimum":0}}],"responses":{"200":{"$ref":"#/components/responses/Ok"},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"}}}},"/v1/places/{id}":{"get":{"x-worker-keyless":true,"summary":"One place with its path (ancestors, country first)","parameters":[{"name":"id","example":"TR-35","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"$ref":"#/components/responses/Ok"},"404":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"}}}},"/v1/places/{id}/boundary":{"get":{"summary":"The boundary as one GeoJSON Feature (application/geo+json, not wrapped in `data`), ready for MapLibre. properties: id, name, detail, dataset_version, attribution. Sent gzip-compressed when the client accepts gzip.","parameters":[{"name":"id","example":"TR-35","in":"path","required":true,"schema":{"type":"string"}},{"name":"detail","example":"overview","in":"query","schema":{"enum":["overview","standard","full"],"default":"overview"},"description":"overview is for country and region maps, standard for a city view, full is the source geometry"}],"responses":{"200":{"description":"A GeoJSON Feature","content":{"application/geo+json":{"schema":{"type":"object","required":["type","geometry","properties"]}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"}}}},"/v1/contains":{"get":{"summary":"Every unit whose land contains the point (country, region, county; in Turkey also mahalle), most general first; match is none at sea or outside the loaded countries","parameters":[{"name":"lat","example":38.4237,"in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","example":27.1428,"in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180}}],"responses":{"200":{"$ref":"#/components/responses/Ok"},"400":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/timezone":{"get":{"summary":"IANA timezone of a point (timezone-boundary-builder polygons: land and territorial waters) with the current UTC offset, DST flag and local time; match is none on the open sea. `dst` is true when the zone's clocks are advanced at that instant: its offset is the larger of the two it shows in that year (1 January and 1 July); a zone with one offset all year is never DST (Morocco: +01:00 and the +00:00 of Ramadan are both `dst: false`). When zones share an edge or overlap, `ambiguous` is true, `timezone` and the other fields are the first zone by name and `candidates` lists all of them (each with its own offset, dst and local time). 503 NOT_READY on a dataset built before the feature","parameters":[{"name":"lat","example":38.4237,"in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","example":27.1428,"in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180}}],"responses":{"200":{"$ref":"#/components/responses/Ok"},"400":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/nearby":{"get":{"x-worker-forward":true,"summary":"The nearest populated places (GeoNames cities500: 500 inhabitants or more, or a seat of government) with distance in km, population and path, nearest first. 503 NOT_READY on a dataset built before the feature","parameters":[{"name":"lat","example":38.4237,"in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","example":27.1428,"in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"limit","example":10,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"Default 10"},{"name":"radius","example":50,"in":"query","schema":{"type":"integer","minimum":1,"maximum":500},"description":"Kilometres, default 100; places farther away are not returned"},{"$ref":"#/components/parameters/lang"}],"responses":{"200":{"$ref":"#/components/responses/Ok"},"400":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/postal":{"get":{"summary":"The places of a postal code (GeoNames); case, spaces and hyphens in the code are ignored. `partial` is true for the countries GeoNames gives only in part (CA, NL, GB: first part; CL, CN, AR: first digits; IE, MT: first letters; BR: major codes). 503 NOT_READY on a dataset built before the feature","parameters":[{"name":"country","example":"TR","in":"query","required":true,"schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"code","example":"35030","in":"query","required":true,"schema":{"type":"string","maxLength":20}},{"name":"limit","example":10,"in":"query","schema":{"type":"integer","minimum":1,"maximum":1000},"description":"Default 100"},{"name":"offset","example":0,"in":"query","schema":{"type":"integer","minimum":0,"maximum":10000},"description":""}],"responses":{"200":{"$ref":"#/components/responses/Ok"},"400":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/postal/nearby":{"get":{"x-worker-forward":true,"summary":"The postal codes nearest to a point (GeoNames), nearest first, with distance in km. 503 NOT_READY on a dataset built before the feature","parameters":[{"name":"lat","example":38.4237,"in":"query","required":true,"schema":{"type":"number","minimum":-90,"maximum":90}},{"name":"lon","example":27.1428,"in":"query","required":true,"schema":{"type":"number","minimum":-180,"maximum":180}},{"name":"limit","example":10,"in":"query","schema":{"type":"integer","minimum":1,"maximum":100},"description":"Default 10"},{"name":"radius","example":50,"in":"query","schema":{"type":"integer","minimum":1,"maximum":500},"description":"Kilometres, default 50"}],"responses":{"200":{"$ref":"#/components/responses/Ok"},"400":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/v1/phone":{"get":{"x-worker-keyless":true,"summary":"Validate and format a phone number","parameters":[{"name":"number","example":"+905321234567","in":"query","required":true,"schema":{"type":"string","maxLength":40},"description":"Send a leading + as %2B"},{"name":"country","example":"TR","in":"query","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"},"description":"Default region for numbers without a + prefix"}],"responses":{"200":{"$ref":"#/components/responses/Ok"},"400":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer"}},"parameters":{"lang":{"name":"lang","example":"tr,en","in":"query","schema":{"type":"string"},"description":"Comma-separated BCP 47 tags (max 5), e.g. en,de. Adds `names`; null means we do not have that language."}},"responses":{"Ok":{"description":"{data, meta: {dataset_version, attribution}}","content":{"application/json":{"schema":{"type":"object","required":["data","meta"]}}}},"Error":{"description":"{status: failed, code}","content":{"application/json":{"schema":{"type":"object","required":["status","code"],"properties":{"status":{"const":"failed"},"code":{"$ref":"#/components/schemas/ErrorCode"},"replaced_by":{"type":["string","null"]}}}}}}},"schemas":{"ErrorCode":{"enum":["INVALID_REQUEST","UNAUTHORIZED","NOT_FOUND","METHOD_NOT_ALLOWED","REQUEST_TIMEOUT","PLACE_RETIRED","PAYLOAD_TOO_LARGE","RATE_LIMITED","CAPACITY_EXCEEDED","INTERNAL_ERROR","NOT_READY","BOUNDARY_UNAVAILABLE"]}}}}