Postal code API: code lookup and nearest postal codes
Find the places a postal code belongs to, or get the postal codes nearest to a coordinate. Geo API serves postal codes for about 120 countries; in Turkey every code is linked to its district and the district's stable ID.
Postal code lookup
/v1/postal?country=TR&code=34710 returns the places of a code: the place name, the region and district names, an approximate coordinate and its accuracy. Rows in Turkey link to the district through place_id and path, so a code turns straight into a province and district ID.
Spaces and hyphens are ignored. A code can have more than one place; page with limit and offset.
Postal codes nearest to a coordinate
/v1/postal/nearby?lat=&lon= returns the codes nearest to a point with their distance in km, nearest first. Use it to suggest the postal code field of an address form from the user's location.
Coverage and limits
The source is GeoNames (CC BY 4.0). For the United Kingdom, Canada and the Netherlands only the first part of the code is available; rows from these and other countries with partial codes carry partial: true. Most coordinates are placed by an algorithm, so every row carries its accuracy.
Example request and response
The code 34710 in Kadıköy: the place name, province, district and the district's ID. This endpoint needs an API key.
Request
curl -H "Authorization: Bearer $GEO_API_KEY" "https://api.forlab.io/geo/v1/postal?country=TR&code=34710"Response excerpt
{
"data": [
{
"country": "TR", "code": "34710", "place_name": "Caferağa",
"admin1": "İstanbul", "admin2": "Kadiköy", "admin3": null,
"lat": 40.9887, "lon": 29.0236, "accuracy": 4, "partial": false,
"place_id": "TR-A73FCPZ0",
"path": [
{ "id": "TR", "name": "Türkiye", "type": "country" },
{ "id": "TR-34", "name": "İstanbul", "type": "region" },
{ "id": "TR-A73FCPZ0", "name": "Kadıköy", "type": "county" }
]
}
],
"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": "postal", "items": [{"country": "TR", "code": "34710"}, {"country": "DE", "code": "10115"}]}What it costs
- Apify Actor, code lookup (postal operation): $0.10 per 1,000 rows returned.
- Apify Actor, nearest postal codes (postal_nearby operation): $0.30 per 1,000 coordinate lookups.
- These endpoints have no free keyless use; for a key, email api@forlab.io.
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
Are Turkish postal codes linked to a neighborhood?
No, to the district. place_name can be a neighborhood name, but place_id and path point to the district. To find the neighborhood of a point, use the reverse geocoding endpoint.
Which countries are covered?
About 120 countries. For the United Kingdom, Canada and the Netherlands only the first part of the code is available; codes can also be partial for Argentina, Brazil, Chile, China, Ireland and Malta, and those rows carry partial: true.
Is the postal data up to date?
Yes, the postal codes are kept up to date from GeoNames. Every reply names the data version it came from in meta.dataset_version.
Can I get the boundary of a postal code?
No. Postal codes come as an approximate point, not a boundary; for province and district boundaries, use Geo API's boundary endpoint.