Geo Reference: Places, Boundaries, Phone, Postal & Timezone avatar

Geo Reference: Places, Boundaries, Phone, Postal & Timezone

Pricing

from $0.10 / 1,000 reference lookups

Go to Apify Store
Geo Reference: Places, Boundaries, Phone, Postal & Timezone

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

ForLab Digital

Maintained by Community

Actor stats

0

Bookmarked

2

Total users

1

Monthly active users

2 hours ago

Last modified

Features

Limited permissions

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 input with its zero-based index, so nothing you send is lost.
  • A reason for every miss. not_found rows carry the API's code (NOT_FOUND, PLACE_RETIRED with replaced_by, BOUNDARY_UNAVAILABLE); invalid rows say which item could not become a request.
  • Only answered lookups are charged. ok and not_found rows cost one event, and a list (places, postal, countries without cc) one per entry its data returns, at least one; invalid items, 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

OperationItem fieldsReturnsPrice per 1,000
countriescc (optional; omit for all), langAll 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
placeid (required), langOne place with its path: ancestors, country first$0.10
placesparent or q (exactly one), country (with q), lang, limit, offsetThe 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
phonenumber (required), country (default region)The number validated, formatted, and split into country and national parts$0.10
postalcountry, code (required), limit, offsetThe places of a postal code, with partial flagged where the source covers only part of the country$0.10 per 1,000 entries returned
containslat, lon (required)Every unit whose land contains the point, most general first (match: "none" at sea)$0.30
timezonelat, lon (required)The IANA timezone, current UTC offset, DST flag and local time of the point$0.30
nearbylat, lon (required), limit, radius, langThe nearest populated places with distance in km, population and containing units$0.30
postal_nearbylat, lon (required), limit, radiusThe postal codes nearest to the point, nearest first$0.30
boundaryid (required), detail: overview, standard or fullThe 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-ok row (NOT_FOUND, INVALID_REQUEST, PLACE_RETIRED, BOUNDARY_UNAVAILABLE, NOT_READY, …) or our transport codes (REQUEST_FAILED, REQUEST_TIMEOUT, RESPONSE_TOO_LARGE, PLATFORM_ERROR). A PLACE_RETIRED row also carries replaced_by.
  • boundary (boundary operation, ok rows): {key, url, bytes} — the GeoJSON Feature in the run's default key-value store, gzip-compressed with Content-Encoding: gzip, data holds its properties (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)

EventPriceCharged per
Reference lookup$0.0001place, phone or countries (with cc) item; each entry a places, postal or countries (all) list returns, at least one per item
Coordinate lookup$0.0003contains, timezone, nearby, postal_nearby item
Boundary lookup$0.001boundary item with overview or standard detail
Full boundary lookup$0.003boundary item with full detail
Actor start$0.001run

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.