Geo Reference: Places, Boundaries, Phone, Postal & Timezone
Pricing
from $0.10 / 1,000 reference lookups
Geo Reference: Places, Boundaries, Phone, Postal & Timezone
Country profiles, administrative units with GeoJSON boundaries (Turkey il/ilçe/mahalle), phone validation, postal codes, nearest places, reverse geocoding and timezones from one versioned worldwide dataset. One row per item, misses included. From $0.0001 per lookup.
Pricing
from $0.10 / 1,000 reference lookups
Rating
0.0
(0)
Developer
ForLab Digital
Maintained by CommunityActor stats
0
Bookmarked
2
Total users
1
Monthly active users
2 hours ago
Last modified
Categories
Features
Share
Geo Reference: countries, places, boundaries, phone, postal and timezone lookups
Send a list of items. Each becomes one request to the ForLab Geo API and one result row, from a single versioned dataset: countries with their calling codes, currencies and languages; administrative units worldwide (Turkey down to ilçe, with every official mahalle and köy); their boundaries as GeoJSON; phone number validation; postal codes; the nearest populated places; and the timezone of any point on land.
- One row per item, misses included. Every row keeps your item under
inputwith its zero-basedindex, so nothing you send is lost. - A reason for every miss.
not_foundrows carry the API's code (NOT_FOUND,PLACE_RETIREDwithreplaced_by,BOUNDARY_UNAVAILABLE);invalidrows say which item could not become a request. - Only answered lookups are charged.
okandnot_foundrows cost one event, and a list (places,postal,countrieswithoutcc) one per entry itsdatareturns, at least one;invaliditems, our failures and skipped items are free. An item that would pass your cost limit is skipped, never charged. - Boundaries download as files. A boundary row links its GeoJSON record in the run's key-value store — a full country boundary is too large for a dataset row.
Input
One operation per run, and a list of items for it:
{"operation": "place","items": [{"id": "TR-34", "lang": "en"},{"id": "DE"}]}
Operations
| Operation | Item fields | Returns | Price per 1,000 |
|---|---|---|---|
countries | cc (optional; omit for all), lang | All countries and dependencies, or one country's names, calling codes, currencies, languages, timezones and levels | $0.10 (with cc); without cc: $0.10 per 1,000 entries returned |
place | id (required), lang | One place with its path: ancestors, country first | $0.10 |
places | parent or q (exactly one), country (with q), lang, limit, offset | The children of a place (country → region → county → mahalle), or a name-prefix search with each hit's path | $0.10 per 1,000 entries returned |
phone | number (required), country (default region) | The number validated, formatted, and split into country and national parts | $0.10 |
postal | country, code (required), limit, offset | The places of a postal code, with partial flagged where the source covers only part of the country | $0.10 per 1,000 entries returned |
contains | lat, lon (required) | Every unit whose land contains the point, most general first (match: "none" at sea) | $0.30 |
timezone | lat, lon (required) | The IANA timezone, current UTC offset, DST flag and local time of the point | $0.30 |
nearby | lat, lon (required), limit, radius, lang | The nearest populated places with distance in km, population and containing units | $0.30 |
postal_nearby | lat, lon (required), limit, radius | The postal codes nearest to the point, nearest first | $0.30 |
boundary | id (required), detail: overview, standard or full | The place's boundary as one GeoJSON Feature, saved to the run's key-value store; the row links to it | $1.00 (overview, standard) / $3.00 (full) |
More examples:
{"operation": "places", "items": [{"parent": "TR"}, {"q": "kadikoy", "country": "TR", "lang": "en"}]}{"operation": "contains", "items": [{"lat": 40.9903, "lon": 29.0291}]}{"operation": "phone", "items": [{"number": "+905321234567"}, {"number": "05321234567", "country": "TR"}]}{"operation": "postal", "items": [{"country": "TR", "code": "34710"}, {"country": "GB", "code": "SW1A"}]}{"operation": "boundary", "items": [{"id": "TR-34", "detail": "standard"}, {"id": "DE", "detail": "full"}]}
Names are the local primary name; lang=en,de (up to 5 tags) adds names. limit and radius start at 1. IDs are stable: countries are ISO 3166-1 (TR), first-level regions ISO 3166-2 (TR-34), deeper units opaque (<CC>-<8 characters>). A retired ID answers PLACE_RETIRED with replaced_by. Cache lists per dataset_version; the run summary records the version it served.
Output
Each item produces one dataset row, in completion order (sort by index for the input order):
{"index": 0,"input": {"id": "TR-34", "lang": "en"},"status": "ok","data": {"id": "TR-34", "name": "İstanbul", "type": "region", "local_type": "il", "country": "TR", "path": [...]}}
status:ok(answered),not_found(404/410 from the API),invalid(the item could not become a request; free),failed(the API was down, refused, timed out after one retry, or the row could not be saved; free),skipped(never sent: past the free-plan item cap, past your cost limit, or past the run timeout).code: the API's error code on every non-okrow (NOT_FOUND,INVALID_REQUEST,PLACE_RETIRED,BOUNDARY_UNAVAILABLE,NOT_READY, …) or our transport codes (REQUEST_FAILED,REQUEST_TIMEOUT,RESPONSE_TOO_LARGE,PLATFORM_ERROR). APLACE_RETIREDrow also carriesreplaced_by.boundary(boundary operation,okrows):{key, url, bytes}— the GeoJSON Feature in the run's default key-value store, gzip-compressed withContent-Encoding: gzip,dataholds itsproperties(id, name, detail, dataset_version, attribution). Download the record with your Apify token (curl --compressed "…/records/boundary-0" -H "Authorization: Bearer $APIFY_TOKEN") or open it in the Console's Storage tab; API clients decompress it automatically.
The OUTPUT record summarizes the run: counts per status, charged_events per event, skipped_reasons, the free-plan cap when it applied, and the dataset_version and attribution of the data served.
Pricing (pay per event)
| Event | Price | Charged per |
|---|---|---|
| Reference lookup | $0.0001 | place, phone or countries (with cc) item; each entry a places, postal or countries (all) list returns, at least one per item |
| Coordinate lookup | $0.0003 | contains, timezone, nearby, postal_nearby item |
| Boundary lookup | $0.001 | boundary item with overview or standard detail |
| Full boundary lookup | $0.003 | boundary item with full detail |
| Actor start | $0.001 | run |
Only ok and not_found rows are charged; invalid, failed and skipped items are free. A list row is still one dataset row: its charge counts the entries in its data, never meta.total, so paging with limit and offset pays for what each page returns. Charges are sent after your results are saved, never past your run cost limit (maxTotalChargeUsd), and each boundary is one item however large its geometry. A list item holds its limit (or the API's default: 1,000 children, 20 search hits, 100 postal places, every country) against your cost limit until it is answered, then gives back what it did not return; set limit to fit more lists into a small budget. On the Apify free plan a run is capped at 1,000 items (the skipped rows say so); your $5 monthly credit covers about 16,000 coordinate lookups.
Coverage
Turkey's il, ilçe and every official mahalle and köy come from official lists, so these lists are complete; il and ilçe boundaries are complete, mahalle and köy boundaries are partial and counted. The rest of the world comes from open data, and each country's levels say whether their list is complete or partial (partial: not compared with an official list). See the per-country table with unit and boundary counts on the coverage page.
Data and licences
One versioned dataset, built from official and open sources: TÜİK (Turkish Statistical Institute, ADNKS), © OpenStreetMap contributors and Overture Maps Foundation (ODbL 1.0), timezone-boundary-builder (ODbL 1.0), GeoNames (CC BY 4.0), CLDR (Unicode License v3), tzdata (public domain) and libphonenumber (Apache-2.0). Every reply carries the full credit in its metadata, and the run summary repeats it. Turkey's mahalle and köy list is the official TÜİK list (32,254 mahalle and 18,183 köy), and their boundaries are partial. The dataset is kept up to date from official and open sources. Boundaries are land only. If you redistribute the data or a derived product, keep the ODbL attribution.
Use it from code or an AI agent
Start a run through the Apify API and read its dataset; no knowledge of this Actor's code is needed:
curl -X POST "https://api.apify.com/v2/acts/forlab~geo-reference/run-sync-get-dataset-items?token=$APIFY_TOKEN" \-H "Content-Type: application/json" \-d '{"operation":"timezone","items":[{"lat":40.9903,"lon":29.0291}]}'
The same data is available directly at api.forlab.io/geo/v1 with an API key, one call at a time.