# Geocoder - Address to Coordinates & Reverse (`benthepythondev/geocoder-openstreetmap`) Actor

Turn addresses or place names into coordinates (forward geocoding) and coordinates back into addresses (reverse geocoding), with structured address parts, bounding box, OSM ids and place type. Reliable via the public OpenStreetMap Nominatim API, no API key.

- **URL**: https://apify.com/benthepythondev/geocoder-openstreetmap.md
- **Developed by:** [Ben](https://apify.com/benthepythondev) (community)
- **Categories:** Lead generation, Real estate, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 geocoding results

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

## 🌍 Geocoder (OpenStreetMap)

Turn addresses or place names into coordinates (forward geocoding) and turn coordinates back into addresses (reverse geocoding) — with full structured address parts, bounding box, OSM ids and place type. Powered by the public OpenStreetMap Nominatim API, so it's reliable and needs no API key. Requests are rate-limited to respect the OSM usage policy.

Built for enriching lead lists and CRMs, mapping, real-estate data and location pipelines. Export to JSON/CSV/Excel, run on a schedule, call via API, or connect to Make, Zapier or n8n.

### 🔎 What is the Geocoder?

Pass addresses to get latitude/longitude and a parsed address — or pass `lat,lon` coordinates to get the nearest address back. Optionally restrict forward results to a country.

#### What data does it extract?

- **Latitude and longitude**
- **Full display name** and **place name**
- **Structured address**: house number, road, city, state, postcode, country, country code
- **Place type and category** (e.g. attraction, city, building)
- **Importance** score and **bounding box**
- **OSM type and id**, place id

### ⬇️ Input

| Field | Type | Description |
|-------|------|-------------|
| `addresses` | array | Addresses/place names to geocode, e.g. `Eiffel Tower, Paris`. |
| `coordinates` | array | Optional: `lat,lon` pairs to reverse-geocode. |
| `countryCode` | string | Optional: restrict forward results to a country (ISO alpha-2). |
| `maxResultsPerQuery` | integer | Matches per address. Default `1`. |

#### Example input

```json
{
  "addresses": ["Eiffel Tower, Paris", "1600 Amphitheatre Parkway, Mountain View"],
  "maxResultsPerQuery": 1
}
````

### ⬆️ Output

One record per result:

```json
{
  "query": "Eiffel Tower, Paris",
  "display_name": "Eiffel Tower, 5, Avenue Anatole France, Paris, France",
  "lat": "48.8582599",
  "lon": "2.2945006",
  "type": "attraction",
  "category": "tourism",
  "importance": 0.79,
  "osm_type": "way",
  "osm_id": 5013364,
  "road": "Avenue Anatole France",
  "city": "Paris",
  "postcode": "75007",
  "country": "France",
  "country_code": "fr",
  "bounding_box": ["48.857", "48.859", "2.293", "2.296"]
}
```

### 💡 Use cases

- 📍 **Lead & CRM enrichment** — add coordinates and clean addresses to records.
- 🗺️ **Mapping & visualization** — plot addresses on a map.
- 🏠 **Real-estate data** — standardize and locate property addresses.
- 🤖 **Automation** — geocode inside Make/Zapier/n8n workflows.

### ❓ FAQ

**Do I need an API key or login?** No — it uses OpenStreetMap Nominatim.

**Does it do reverse geocoding?** Yes — pass `lat,lon` pairs in `coordinates`.

**Can I restrict to a country?** Yes — set `countryCode`.

**How fast is it?** Requests are throttled to ~1/second to respect the OSM usage policy.

**What address parts do I get?** House number, road, city, state, postcode, country and country code.

**How does pricing work?** Pay per result returned. No subscription.

**Is it legal?** It uses the public OSM Nominatim API. Use responsibly and within the OSM usage policy.

### 🔗 You might also like

- [Google Maps Email Scraper](https://apify.com/benthepythondev/google-maps-email-scraper) — local business leads + emails.
- [Public Holidays Scraper](https://apify.com/benthepythondev/public-holidays-scraper) — holidays by country.
- [Website Contact Extractor](https://apify.com/benthepythondev/website-contact-extractor) — emails & phones from sites.

***

**Keywords:** geocoder, geocoding api, address to coordinates, reverse geocoding, openstreetmap, nominatim, lat lon lookup, address parser, location data, lead enrichment, gps coordinates, batch geocoding, address standardization, mapping data

### Production workflow

This Actor is designed for operations teams, property analysts, logistics workflows and location-data developers. Normalize input addresses first, retain the original query beside every match, and review importance, type and bounding-box fields before using a coordinate in routing, territory or property workflows. Small, repeatable runs are easier to audit than occasional unlimited exports: they expose source changes quickly, reduce duplicate processing and keep automation costs predictable. Use the input defaults as a smoke test, then widen the query only after confirming that the returned fields match the downstream workflow.

Treat each dataset row as source evidence captured at a point in time, not as a permanent fact. Preserve the canonical identifier and source URL, add the run timestamp in the receiving system, and deduplicate before writing to a CRM, spreadsheet, warehouse or alert channel. For recurring monitoring, compare the newest dataset with the previous successful run and send only additions or material changes onward. That pattern avoids repeated notifications and makes the automation more useful over time.

### Data quality and interpretation

The primary output includes `query`, `display_name`, `lat`, `lon`, `type`, `category`, `importance`, `place_id`, `osm_type`, `osm_id`, `name`, `house_number`. Availability depends on what the source publishes for a particular result. Empty values are retained as null or empty fields rather than invented. Search rank is source-specific and can change with language, geography, query wording and time. Validate critical decisions against the linked source page, especially when the data is used for outreach, compliance, pricing, routing or reporting.

Use bounded inputs and respect the source's published interface. The Actor does not bypass logins or collect private account data. Avoid placing passwords, session cookies, personal access tokens or confidential records in Actor input. If a public source changes its response shape, attach a reproducible public input and run ID to an Actor issue so the parser can be updated without exposing private data.

### Automation and cost control

The default dataset can be exported as JSON, CSV, Excel, XML or RSS and can be consumed through the Apify API. In Make, Zapier or n8n, start the Actor, wait for the run to finish, then read default-dataset items. In code, store the Actor run ID and dataset ID alongside the imported rows so every record remains traceable. Apply filters after collection only when the source cannot express them directly; source-side filtering usually reduces cost and noise.

This Actor uses pay-per-event billing. A result event is charged only when a structured row is saved to the default dataset. Keep test runs small, estimate expected row volume before scheduling broad searches, and use platform spending limits for unattended workflows. Failed requests and empty searches should not create result events.

### Support and feedback

If the Actor saves time in a real workflow, please leave a short Apify Store review describing the use case and the fields that were most useful. Reviews help other users evaluate the product and help prioritize maintenance. For support, open an Actor issue with the run ID, public input, expected behavior and one affected field. Do not include credentials or confidential information.

# Actor input Schema

## `addresses` (type: `array`):

Addresses or place names to turn into coordinates, e.g. 'Eiffel Tower, Paris'.

## `coordinates` (type: `array`):

Optional: 'lat,lon' pairs to turn into addresses, e.g. '48.8584,2.2945'.

## `countryCode` (type: `string`):

Optional: restrict forward results to a country (ISO alpha-2), e.g. 'fr'.

## `maxResultsPerQuery` (type: `integer`):

How many matches to return per address (forward geocoding).

## Actor input object example

```json
{
  "addresses": [
    "Eiffel Tower, Paris"
  ],
  "maxResultsPerQuery": 1
}
```

# Actor output Schema

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

No description

# 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 = {
    "addresses": [
        "Eiffel Tower, Paris"
    ],
    "maxResultsPerQuery": 1
};

// Run the Actor and wait for it to finish
const run = await client.actor("benthepythondev/geocoder-openstreetmap").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 = {
    "addresses": ["Eiffel Tower, Paris"],
    "maxResultsPerQuery": 1,
}

# Run the Actor and wait for it to finish
run = client.actor("benthepythondev/geocoder-openstreetmap").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "addresses": [
    "Eiffel Tower, Paris"
  ],
  "maxResultsPerQuery": 1
}' |
apify call benthepythondev/geocoder-openstreetmap --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=benthepythondev/geocoder-openstreetmap",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Geocoder - Address to Coordinates & Reverse",
        "description": "Turn addresses or place names into coordinates (forward geocoding) and coordinates back into addresses (reverse geocoding), with structured address parts, bounding box, OSM ids and place type. Reliable via the public OpenStreetMap Nominatim API, no API key.",
        "version": "1.0",
        "x-build-id": "1xsCG7lOeB8dhxFAQ"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/benthepythondev~geocoder-openstreetmap/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-benthepythondev-geocoder-openstreetmap",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/benthepythondev~geocoder-openstreetmap/runs": {
            "post": {
                "operationId": "runs-sync-benthepythondev-geocoder-openstreetmap",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/benthepythondev~geocoder-openstreetmap/run-sync": {
            "post": {
                "operationId": "run-sync-benthepythondev-geocoder-openstreetmap",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "addresses": {
                        "title": "Addresses (forward geocode)",
                        "type": "array",
                        "description": "Addresses or place names to turn into coordinates, e.g. 'Eiffel Tower, Paris'.",
                        "default": [
                            "Eiffel Tower, Paris"
                        ],
                        "items": {
                            "type": "string"
                        }
                    },
                    "coordinates": {
                        "title": "Coordinates (reverse geocode)",
                        "type": "array",
                        "description": "Optional: 'lat,lon' pairs to turn into addresses, e.g. '48.8584,2.2945'.",
                        "items": {
                            "type": "string"
                        }
                    },
                    "countryCode": {
                        "title": "Country code filter",
                        "type": "string",
                        "description": "Optional: restrict forward results to a country (ISO alpha-2), e.g. 'fr'."
                    },
                    "maxResultsPerQuery": {
                        "title": "Max results per address",
                        "minimum": 1,
                        "maximum": 10,
                        "type": "integer",
                        "description": "How many matches to return per address (forward geocoding).",
                        "default": 1
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```