# Turkey Province, District & Mahalle API: Reverse Geocoding (`forlab/geo-reference`) Actor

Turkey's official il, ilçe and mahalle/köy list, province and district boundaries as GeoJSON, and point-in-polygon reverse geocoding to the neighborhood. Also postal codes, nearby places, timezones, phone validation and countries worldwide. Pay per lookup, no monthly minimum.

- **URL**: https://apify.com/forlab/geo-reference.md
- **Developed by:** [ForLab Digital](https://apify.com/forlab) (community)
- **Categories:** Developer tools, Travel, Integrations
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.10 / 1,000 reference lookups

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Turkey Province, District & Mahalle API: Reverse Geocoding

Turkey Province, District & Mahalle API is the Actor for **il, ilçe and mahalle data**: Turkey's official mahalle and köy list from TÜİK, province and district boundaries as GeoJSON, and a **point-in-polygon reverse geocode** that turns a latitude and longitude into the province, district and, where it has a boundary, the neighborhood. The same dataset also gives postal codes, nearby places, timezones, phone number validation and country profiles for the rest of the world, from the [ForLab Geo API](https://api.forlab.io/docs).

Send a list of items. Each becomes one request and one result row. You need an Apify account and nothing else: the Actor holds the API key. There is no monthly minimum; you pay per lookup.

- **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.
- **Stable IDs.** Countries are ISO 3166-1 (`TR`), first-level regions ISO 3166-2 (`TR-34`), deeper units opaque (`<CC>-<8 characters>`). Store the ID, not the name.

### Task examples

Each example is a complete run input: paste it into the Input tab. One operation per run, as many items as you like.

#### Find the neighborhood (mahalle) for a GPS point

Reverse geocode coordinates to country, province, district and neighborhood (point-in-polygon against real boundaries). A point at sea or outside every unit answers `match: "none"`, never a guess. Neighborhood boundaries are partial, so for some points the answer stops at the district.

```json
{"operation": "contains", "items": [{"lat": 40.9903, "lon": 29.0291}, {"lat": 38.4237, "lon": 27.1428}]}
```

#### List all provinces and districts of Turkey (il ilçe API)

`parent` takes a country, a province or a district ID: `TR` lists the provinces, `TR-34` the districts of İstanbul.

```json
{"operation": "places", "items": [{"parent": "TR"}, {"parent": "TR-34"}]}
```

#### Get every mahalle and köy of a district

A district ID lists its official mahalle and köy from the TÜİK list. Each row has `local_type`: `mahalle` or `köy`.

```json
{"operation": "places", "items": [{"parent": "TR-7N6BAMXN"}]}
```

#### Search a Turkish place by name

A name-prefix search; case, accents and the Turkish dotted and dotless i are ignored. Each hit comes with its parent units.

```json
{"operation": "places", "items": [{"q": "kadikoy", "country": "TR", "lang": "en"}]}
```

#### Look up one place, with its full path

The place with its ancestors, country first, in as many languages as you ask for (`lang`, up to 5 tags).

```json
{"operation": "place", "items": [{"id": "TR-34", "lang": "en,de"}, {"id": "DE"}]}
```

#### Download province and district boundaries as GeoJSON

One GeoJSON Feature per item, saved to the run's key-value store. `overview` suits country and region maps, `standard` a city view, `full` is the source geometry.

```json
{"operation": "boundary", "items": [{"id": "TR-34", "detail": "standard"}, {"id": "TR-35", "detail": "overview"}]}
```

#### Validate and format phone numbers (E.164)

Validity, E.164 and national formats and the number's country. Pass `country` as the default region for numbers without a `+`.

```json
{"operation": "phone", "items": [{"number": "05321234567", "country": "TR"}, {"number": "+4915112345678"}]}
```

#### Convert a postal code to a place

The places of a postal code, with `partial` flagged for countries the source covers only in part.

```json
{"operation": "postal", "items": [{"country": "TR", "code": "34710"}, {"country": "GB", "code": "SW1A"}]}
```

#### Get the timezone for a coordinate

The IANA timezone, current UTC offset, DST flag and local time of a point on land.

```json
{"operation": "timezone", "items": [{"lat": 40.7128, "lon": -74.006}, {"lat": 41.0082, "lon": 28.9784}]}
```

#### Find the nearest cities and postal codes to a point

The nearest populated places with distance in km, population and containing units, and the postal codes nearest to a point.

```json
{"operation": "nearby", "items": [{"lat": 40.9903, "lon": 29.0291, "limit": 5}]}
```

```json
{"operation": "postal_nearby", "items": [{"lat": 40.9903, "lon": 29.0291, "limit": 5}]}
```

#### Get a country profile: calling code, currency, languages

One country's names, calling codes, currencies, languages, timezones and levels; omit `cc` to list every country.

```json
{"operation": "countries", "items": [{"cc": "TR"}, {"cc": "DE", "lang": "tr"}]}
```

### Input

One operation per run, and a list of items for it:

```json
{
  "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 run inputs are in the task examples above.

Names are the local primary name; `lang=en,de` (up to 5 tags) adds `names`. `limit` and `radius` start at 1. 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):

```json
{
  "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)

| 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](https://forlab.io/en/projects/geo-api/coverage).

### 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:

```bash
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](https://api.forlab.io/docs) with an API key, one call at a time.

### Frequently asked questions

#### Is Turkey's mahalle and köy list complete?

Yes. The list comes from TÜİK's official list, so every official mahalle and köy is in it. Only their boundaries are partial: the coverage page counts how many units have one.

#### Can I get the neighborhood for a GPS coordinate?

Yes, with the `contains` operation, where the neighborhood has a boundary. Where it has none, the answer stops at the district and says so.

#### Do I need a Geo API key?

No. The Actor sends its own key. You pay per lookup through Apify, with no monthly minimum. For direct API access with your own key, see the [API documentation](https://forlab.io/en/projects/geo-api/docs).

#### What does a run cost?

Pay per event, listed in the pricing table above. A run is charged only for answered lookups, never past the cost limit you set.

#### Does it work outside Turkey?

Yes. The dataset covers countries worldwide, and each country's levels say whether their list is complete or partial; see the [coverage page](https://forlab.io/en/projects/geo-api/coverage).

### Links

- [Geo API documentation](https://forlab.io/en/projects/geo-api/docs) (Turkish: [dokümantasyon](https://forlab.io/projeler/geo-api/dokumantasyon)): every endpoint, parameter and error code, read from the live OpenAPI.
- [Coverage by country](https://forlab.io/en/projects/geo-api/coverage): unit and boundary counts, complete or partial.
- [Service status](https://status.forlab.io).
- Other ForLab Actors: [CSV/JSON Schema Formatter](https://apify.com/forlab/csv-json-schema-formatter) and [Contact Evidence Enricher](https://apify.com/forlab/contact-evidence-enricher).

# Actor input Schema

## `operation` (type: `string`):

One operation per run; every item becomes one request to the ForLab Geo API and one result row. Item fields by operation — countries: cc (optional two-letter code; omit it for all countries), lang. place: id (required), lang. places: parent (a country, region or county ID) or q (a name prefix; exactly one of the two), country (only with q), lang, limit, offset. phone: number (required, a leading + is allowed), country (default region for numbers without +). postal: country and code (required), limit, offset. contains and timezone: lat and lon (required). nearby and postal_nearby: lat and lon (required), limit, radius, (nearby only) lang. boundary: id (required), detail (overview, standard or full; default overview). A wrong field, a wrong type or an empty value makes that item invalid: the row says so and the item is not charged.

## `items` (type: `array`):

1–5,000 objects (1,000 on the Apify free plan), one lookup each, up to 16 at a time. Every row keeps its item under input with the zero-based index; rows come out in completion order, so sort by index if you need the input order. Nothing is looked up or charged past your run cost limit.

## Actor input object example

```json
{
  "operation": "place",
  "items": [
    {
      "id": "TR"
    },
    {
      "id": "TR-34"
    },
    {
      "id": "TR-35"
    },
    {
      "id": "DE"
    },
    {
      "id": "US"
    }
  ]
}
```

# Actor output Schema

## `results` (type: `string`):

One item per input item: the input under input with its index, a status (ok, not_found, invalid, failed or skipped), the API's code when it answered an error, the API's data when it answered, and for boundaries the key-value record that holds the GeoJSON.

## `summary` (type: `string`):

Counts per status and per charged event, why items were skipped, and the dataset version and attribution of the data served.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "items": [
        {
            "id": "TR"
        },
        {
            "id": "TR-34"
        },
        {
            "id": "TR-35"
        },
        {
            "id": "DE"
        },
        {
            "id": "US"
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("forlab/geo-reference").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "items": [
        { "id": "TR" },
        { "id": "TR-34" },
        { "id": "TR-35" },
        { "id": "DE" },
        { "id": "US" },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("forlab/geo-reference").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "items": [
    {
      "id": "TR"
    },
    {
      "id": "TR-34"
    },
    {
      "id": "TR-35"
    },
    {
      "id": "DE"
    },
    {
      "id": "US"
    }
  ]
}' |
apify call forlab/geo-reference --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,forlab/geo-reference"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/zADfFjvKmuI8U42dP/builds/YeOgec7fBvJI5lffZ/openapi.json
