# OpenStreetMap Geocoder (`cynix_dev/osm-geocoder`) Actor

Forward and reverse geocoding via the free Komoot Photon / OpenStreetMap service. No API key, no scraping, ODbL data. A direct, cheaper alternative to the Google Maps geocoder.

- **URL**: https://apify.com/cynix\_dev/osm-geocoder.md
- **Developed by:** [Cynix Dev](https://apify.com/cynix_dev) (community)
- **Categories:** AI, Agents, Travel
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.17 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

## OpenStreetMap Geocoder

**Forward and reverse geocoding** built on OpenStreetMap data via the free Komoot Photon service — turn place names into coordinates, or coordinates into addresses. No API key, no Google Maps billing account, no per-request contract.

### What it does

Two modes in one Actor:

- **Forward geocoding** (`mode: forward`) — send free text like `Eiffel Tower` or `1600 Pennsylvania Ave` and get ranked matches with latitude, longitude, a display name, an OSM category/type and the underlying OSM identifiers.
- **Reverse geocoding** (`mode: reverse`) — send a `latitude` and `longitude` and get the nearest addressable places back.

Results come from OpenStreetMap under the ODbL licence, which is stated in every record's `licence` field so attribution obligations are never a mystery.

### Features

- **Both directions** — forward (text → coordinates) and reverse (coordinates → address).
- **No API key, no billing account** — a direct alternative to the Google Maps Geocoding API.
- **Language preference** — `language` returns names in `en`, `de`, `fr`, and more.
- **OSM identifiers included** — `osmType` and `osmId` let you join back to raw OpenStreetMap data.
- **Category and type** on every hit, so you can filter to the kind of place you actually want.
- **Licence field on each record** — ODbL attribution is documented in the data itself.
- **No proxy required** — the upstream service is a public API, so runs stay cheap.

### What people use it for

- Batch-geocode a customer, supplier or store list before mapping it.
- Add coordinates to CRM or spreadsheet records that only carry an address.
- Reverse-geocode GPS traces, IoT pings or delivery logs into readable places.
- Give an AI agent or chatbot a location-lookup tool without Google billing.
- Validate and normalise user-entered addresses in a signup flow.

### Forward vs reverse, side by side

Forward geocoding — text in, coordinates out:

```json
{ "mode": "forward", "query": "Eiffel Tower", "limit": 5, "language": "en" }
```

Reverse geocoding — coordinates in, places out:

```json
{ "mode": "reverse", "latitude": 48.8584, "longitude": 2.2945, "limit": 1 }
```

#### Attribution

The underlying data is © OpenStreetMap contributors, licensed under the **Open Database License (ODbL)**. If you publish maps or derived databases built from these results, you must credit OpenStreetMap and respect the ODbL's share-alike terms. The `licence` field is carried on every record as a reminder.

### Input

Set `mode` first: `forward` uses `query`, `reverse` uses `latitude` and `longitude`.

| Field | Type | Default | What it does |
| --- | --- | --- | --- |
| `mode` **(required)** | string | `forward` | forward: text query to coordinates. reverse: coordinates to address. Options: `forward`, `reverse`. |
| `query` | string | `Eiffel Tower` | Free-text location, e.g. 'Eiffel Tower' or '1600 Pennsylvania Ave'. |
| `latitude` | number | — | Latitude for reverse geocoding. |
| `longitude` | number | — | Longitude for reverse geocoding. |
| `limit` | integer | `10` | Max records to return. Range 1–50. |
| `language` | string | `en` | Preferred result language (ISO 639-1), e.g. 'en', 'de', 'fr'. |
| `proxyConfiguration` | object | see below | Proxy settings for targets that block datacenter IPs. Use Apify Residential proxy for best results on sites with anti-bot. |

#### Input example

```json
{
  "mode": "reverse",
  "latitude": 48.8584,
  "longitude": 2.2945,
  "limit": 1,
  "query": "Eiffel Tower",
  "language": "en",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

### Output

One record per match, ordered by relevance. `displayName` is the human-readable label; `lat`/`lon` are the coordinates; `category` and `type` describe what kind of place it is.

Every dataset record contains: `query`, `placeId`, `displayName`, `lat`, `lon`, `type`, `category`, `importance`, `osmType`, `osmId`, `licence`, `address`, `boundingBox`, `fetchedAt`.

#### Output example

A real record from a run of this Actor:

```json
{
  "query": null,
  "placeId": "13665571861",
  "displayName": "Madame Brasserie, Avenue Anatole France, 5, Paris, Île-de-France, France",
  "lat": "48.8584481",
  "lon": "2.2945757",
  "type": "fast_food",
  "category": "amenity",
  "importance": "amenity/fast_food",
  "osmType": "N",
  "osmId": "13665571861",
  "licence": "ODbL (OpenStreetMap contributors)",
  "address": {
    "name": "Madame Brasserie",
    "street": "Avenue Anatole France",
    "city": "Paris",
    "country": "France"
  },
  "boundingBox": null,
  "fetchedAt": "2026-08-22T06:32:15.811Z"
}
```

Export the dataset as JSON, CSV, Excel, XML or JSONL from the Console, or pull it programmatically through the Apify API and any of the official clients.

### How to use it

1. Click **Try for free** (or **Start** if you already have an Apify account).
2. Fill in the input fields described above — the defaults already produce a working run.
3. Press **Start** and watch the log; results stream into the dataset as they are found.
4. When the run finishes, open the **Output/Storage** tab and export as JSON, CSV or Excel.

Runs can be scheduled (hourly, daily, weekly) and wired into Slack, Google Sheets, Zapier, Make, webhooks or your own backend through Apify integrations. Everything the Console does is also available over the [Apify API](https://docs.apify.com/api/v2).

### Proxy configuration

This Actor accepts a standard Apify **proxy configuration** object. Residential proxy is the default because the target site rate-limits datacenter IP ranges; you can select a specific exit country or supply your own proxy URLs.

```json
{
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

### Pricing

This Actor is billed on Apify's **pay-per-event** model: a small charge when a run starts, plus a charge for each result written to the dataset. You only pay for records you actually receive — a run that finds nothing costs only the start event. Current rates are always shown on the **Pricing** tab of this page, and the run log prints your usage as it goes.

Free-plan credits from Apify cover a large amount of light usage, so you can evaluate the Actor before committing to anything.

### FAQ

#### How is this different from the Google Maps Geocoding API?

Same job, different data and commercial model: OpenStreetMap data via a free public service, with no API key, no billing account and no per-1000-request pricing. Google's coverage of house numbers and business POIs is stronger in some regions; OSM is often better on amenities and in mapped-community areas. For bulk work the cost difference is substantial.

#### Why did a reverse lookup return a restaurant instead of a street address?

Reverse geocoding returns the nearest *mapped* features, and in dense areas that is frequently a POI rather than a street address. Raise `limit` to see several candidates, then filter on `category` or `type` for the kind of feature you want.

#### Can I geocode a whole spreadsheet in one run?

Each run handles one query or one coordinate pair. To batch, create an Apify **task** per query, or call the Actor from the API in a loop — the runs are lightweight and inexpensive.

#### Do I need to enable the proxy?

No. The upstream service is a public API and doesn't block datacenter IPs, so the proxy is off by default.

#### Is the data good enough for production?

For most address and POI lookups, yes — OpenStreetMap is the same data behind many commercial products. Coverage is uneven by region, so spot-check your target geography before you depend on it.

### Other Actors by cynix\_dev

| Actor | What it does |
| --- | --- |
| [Website to RAG Chunks](https://apify.com/cynix_dev/web-to-rag-chunks) | Crawl any website and turn its pages into clean, chunked, metadata-rich Markdown records ready for RAG pipelines, vector stores, … |
| [Dataset Drift & QA Monitor](https://apify.com/cynix_dev/dataset-drift-qa) | Stop finding out your scrapers broke three days late. Point this actor at any Apify dataset or JSON endpoint and it watches the … |
| [Page Change Monitor](https://apify.com/cynix_dev/page-change-monitor) | Monitor web pages for content changes. Diffs each run against the previous snapshot and emits structured change records with … |
| [WHOIS & DNS Enrichment](https://apify.com/cynix_dev/whois-enrichment) | Enrich domains with structured WHOIS data (registrar, registration/expiration dates, status, nameservers) and optional DNS … |
| [Launch Library 2 — Rocket Launch Tracker](https://apify.com/cynix_dev/launch-library-launches) | Upcoming, previous, and specific rocket launches from The Space Devs' Launch Library 2 API. |

### Legal and responsible use

This Actor collects only publicly available information. You are responsible for how you use the data, including compliance with the target site's Terms of Service, robots directives, copyright, and data protection law such as GDPR and CCPA. Do not use it to gather personal data without a lawful basis.

### Support and feedback

Found a bug, hit a site change, or need an extra field? Open a ticket on the **Issues** tab of this Actor — issues are read and fixed. Feature requests and custom-scraper enquiries are welcome through the same channel.

# Actor input Schema

## `mode` (type: `string`):

forward: text query to coordinates. reverse: coordinates to address.

## `query` (type: `string`):

Free-text location, e.g. 'Eiffel Tower' or '1600 Pennsylvania Ave'.

## `latitude` (type: `number`):

Latitude for reverse geocoding.

## `longitude` (type: `number`):

Longitude for reverse geocoding.

## `limit` (type: `integer`):

Max records to return.

## `language` (type: `string`):

Preferred result language (ISO 639-1), e.g. 'en', 'de', 'fr'.

## `proxyConfiguration` (type: `object`):

Proxy settings for targets that block datacenter IPs. Use Apify Residential proxy for best results on sites with anti-bot.

## Actor input object example

```json
{
  "mode": "forward",
  "query": "Eiffel Tower",
  "limit": 10,
  "language": "en",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `query` (type: `string`):

Original query (forward).

## `placeId` (type: `string`):

OSM place id.

## `displayName` (type: `string`):

Full display name.

## `lat` (type: `string`):

Latitude.

## `lon` (type: `string`):

Longitude.

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

Feature type.

## `category` (type: `string`):

OSM key.

## `osmType` (type: `string`):

OSM type (node/way/relation).

## `osmId` (type: `string`):

OSM id.

## `licence` (type: `string`):

Data licence.

## `fetchedAt` (type: `string`):

ISO timestamp.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("cynix_dev/osm-geocoder").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("cynix_dev/osm-geocoder").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 '{}' |
apify call cynix_dev/osm-geocoder --silent --output-dataset

```

## MCP server setup

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

```

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/Ec316MtFbW4XQ7QJV/builds/Bltq5ReASply5KXaf/openapi.json