Reverse geocoding API: coordinates to country, state and district
Send a latitude and longitude, and Geo API finds the country, state or province and district that contain the point, tested against real boundaries, adding the neighborhood in Turkey where it has a boundary. It turns a GPS position, a delivery point or a photo's coordinates into administrative units.
How it works
/v1/contains?lat=&lon= returns every unit that contains the point, most general first: country, state or province, district, neighborhood. Each unit comes with its stable ID, type and name; use the ID with /v1/places/{id} for the full detail.
If the point is at sea or inside no unit, the reply is match: "none" with an empty list. It says so instead of guessing the nearest place and returning the wrong state.
Coverage in Turkey and worldwide
Countries and first-level regions (states, provinces) around the world come with their boundaries, and many countries add the level below. A point in Munich returns Germany, the state of Bavaria and the district of München.
In Turkey all 81 provinces and 973 districts have boundaries, so every point on land lands in its province and district. Neighborhood boundaries are partial: only some neighborhoods on the official list have one, so for some points the answer stops at the district.
What it is used for
Prefilling the state and district of an address from the user's location in a mobile app, reporting courier or field-team records by district, and linking the coordinates of listings or stores to administrative units. With the same coordinate you can also get the timezone and the nearest places.
Example request and response
A point in Kadıköy, Istanbul: the reply lists the country, province, district and neighborhood, most general first. This endpoint needs an API key.
Request
curl -H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/contains?lat=40.9903&lon=29.0291"Response excerpt
{
"data": {
"match": "found",
"places": [
{ "id": "TR", "type": "country", "local_type": "country", "name": "Türkiye" },
{ "id": "TR-34", "type": "region", "local_type": "il", "name": "İstanbul" },
{ "id": "TR-A73FCPZ0", "type": "county", "local_type": "ilçe", "name": "Kadıköy" },
{ "id": "TR-3NF9XEBT", "type": "neighborhood", "local_type": "mahalle", "name": "Osmanağa" }
]
},
"meta": { … }
}The same job with the Apify Actor
Without a key, or for a batch, give the Geo Reference Actor a list: each item becomes one result row that keeps the value you sent. Example input:
{"operation": "contains", "items": [{"lat": 40.9903, "lon": 29.0291}]}What it costs
- Apify Actor (contains operation): $0.30 per 1,000 coordinate lookups.
- This endpoint has no free keyless use; for a key, email api@forlab.io.
- You can try it without a key on the live map on the Geo API page.
On Apify you pay as you go: only answered lookups are charged, items that cannot become a request are free, and each run adds a $0.001 start fee. The Apify free plan's $5 monthly credit covers about 16,000 coordinate lookups. For a direct API key, email api@forlab.io.
Frequently asked questions
Does every point return a neighborhood?
No. In Turkey every point on land returns its province and district. A neighborhood comes back only where it has a boundary; not every neighborhood on the official list has one, so for some points the answer stops at the district.
What happens for a point at sea?
The reply is match: "none" with an empty places list; there is no guess. For the places nearest to the point, use the /v1/nearby endpoint.
How do I look up many coordinates?
Give the Geo Reference Actor on Apify a list of coordinates: each becomes one result row, and only answered rows are charged. On the API directly, each coordinate is one request.
Does it return street names and house numbers?
No. Geo API returns administrative units (country, state or province, district, neighborhood); it does not return streets or house numbers.