Nominatim Address Geocoder

Batch geocode addresses to GPS coordinates (forward geocoding) or convert latitude/longitude coordinates back to street addresses (reverse geocoding) using the OpenStreetMap Nominatim API. Powered by the world's largest open geographic database with global coverage across 200+ countries. No API key required. Built-in rate limiting at 1.1 seconds between requests ensures full compliance with Nominatim usage policies. Returns 16 structured fields per result including full address breakdown, OSM metadata, importance scores, and bounding boxes.

---

Why use Nominatim Address Geocoder?

• Completely free geocoding -- unlike Google Maps ($5 per 1,000 requests) or Mapbox (usage-based pricing), Nominatim uses OpenStreetMap data with zero per-request charges and no API key registration
• Two-way address resolution -- forward geocode addresses to coordinates or reverse geocode coordinates to addresses in a single actor, eliminating the need for separate tools
• Batch processing built in -- submit hundreds of addresses or coordinate pairs at once instead of writing custom scripts to loop through individual API calls
• Automatic rate limit compliance -- Nominatim enforces a strict 1 request/second policy and will block violators; this actor spaces requests at 1.1 seconds automatically so you never get banned
• Structured, consistent output -- every result returns the same 16 fields with null-safe handling for failed lookups, making downstream data processing predictable and reliable
• Cloud-native scheduling -- run geocoding jobs on recurring schedules via Apify, trigger runs via webhooks, and pipe results directly into Google Sheets, CRMs, or databases without local infrastructure

---

Key features

• Forward geocoding -- convert street addresses, landmarks, city names, or any place description into precise latitude/longitude GPS coordinates
• Reverse geocoding -- convert GPS coordinate pairs back into fully structured street addresses with city, state, country, and postcode
• Batch processing -- geocode hundreds of addresses or coordinate pairs in a single actor run with automatic queuing
• Country code filtering -- restrict forward geocoding results to a specific country using ISO 3166-1 alpha-2 codes (e.g., US, GB, DE, JP) for higher accuracy
• Multi-language results -- retrieve address components in English, German, French, Spanish, Japanese, or any language supported by OpenStreetMap
• Full address decomposition -- every result includes house number, road, city, state, country, and postcode as separate fields
• OpenStreetMap metadata -- includes OSM type, OSM ID, place type classification, importance ranking score, and geographic bounding box
• Automatic rate limiting -- built-in 1.1-second delay between requests keeps you compliant with Nominatim usage policy without manual throttling
• Null-safe failure handling -- when an address cannot be resolved, the actor returns a record with the original query preserved and all location fields set to null
• Zero configuration -- no API keys, no account registration, no billing setup; just provide addresses and run

---

How to use Nominatim Address Geocoder

Using the Apify Console

1. Navigate to the Nominatim Address Geocoder actor page on Apify Store.
2. Click Try for free to open the actor in the Apify Console.
3. Select the Geocoding Mode -- choose "Forward" to convert addresses to coordinates, or "Reverse" to convert coordinates to addresses.
4. For forward mode, enter your addresses in the Addresses to Geocode field, one per line. Optionally set a Country Code to restrict results.
5. For reverse mode, enter matching lists of Latitudes and Longitudes, one value per line. Both lists must have the same length.
6. Optionally change the Language from the default "en" to receive results in another language.
7. Click Start and wait for the run to complete.
8. View results in the Dataset tab, or export to JSON, CSV, Excel, or other formats.

Using the Apify API or CLI

apify call ryanclinton/nominatim-geocoder \
  --input='{"mode":"forward","queries":["1600 Pennsylvania Ave, Washington DC","Eiffel Tower, Paris","Big Ben, London"],"countryCode":"","language":"en"}'

---

Input parameters

Parameter	Type	Required	Default	Description
mode	Select	No	forward	Geocoding mode. "forward" converts addresses to coordinates. "reverse" converts coordinates to addresses.
queries	String list	No	--	List of addresses, place names, or landmarks to geocode. Used in forward mode only. One address per line.
latitudes	String list	No	--	List of latitude values for reverse geocoding. Must match the length of the longitudes list.
longitudes	String list	No	--	List of longitude values for reverse geocoding. Must match the length of the latitudes list.
countryCode	String	No	--	Restrict forward geocoding to a specific country. Use ISO 3166-1 alpha-2 codes such as "US", "GB", "DE", "FR", "JP".
language	String	No	en	Preferred language for results. Use ISO 639-1 codes: "en", "de", "fr", "es", "ja", "zh", "ar", etc.

Forward geocoding input example

{
    "mode": "forward",
    "queries": [
        "1600 Pennsylvania Ave, Washington DC",
        "Eiffel Tower, Paris, France",
        "Shibuya Crossing, Tokyo",
        "Colosseum, Rome, Italy"
    ],
    "countryCode": "",
    "language": "en"
}

Reverse geocoding input example

{
    "mode": "reverse",
    "latitudes": ["48.8584", "40.7484", "51.5014"],
    "longitudes": ["2.2945", "-73.9857", "-0.1419"],
    "language": "en"
}

Tips for input

• For forward geocoding, include as much detail as possible -- street number, street name, city, state, and country yield the best results.
• Always set the countryCode when you know the target country. This prevents the geocoder from returning matches in the wrong country (e.g., "Springfield" exists in 30+ US states and in other countries).
• For reverse geocoding, use at least 4 decimal places of precision for street-level accuracy.
• The latitudes and longitudes lists must be the same length -- each latitude at index N is paired with the longitude at index N.

---

Output

Each geocoding result contains 16 structured fields. Here is an example of a forward geocoding result:

{
    "query": "1600 Pennsylvania Ave, Washington DC",
    "latitude": 38.8976763,
    "longitude": -77.0365298,
    "displayName": "White House, 1600, Pennsylvania Avenue Northwest, Ward 2, Washington, District of Columbia, 20500, United States",
    "houseNumber": "1600",
    "road": "Pennsylvania Avenue Northwest",
    "city": "Washington",
    "state": "District of Columbia",
    "country": "United States",
    "postcode": "20500",
    "osmType": "way",
    "osmId": 238241022,
    "placeType": "house",
    "importance": 0.782,
    "boundingBox": ["38.8974908", "38.8979247", "-77.0368537", "-77.0360855"],
    "extractedAt": "2025-01-15T14:32:08.123Z"
}

Output fields reference

Field	Type	Description
query	String	The original input address or coordinate pair that was geocoded
latitude	Number / null	GPS latitude of the resolved location
longitude	Number / null	GPS longitude of the resolved location
displayName	String / null	Full formatted address as returned by Nominatim
houseNumber	String / null	Street number or house number component
road	String / null	Street or road name component
city	String / null	City, town, village, or municipality name
state	String / null	State, province, or region name
country	String / null	Full country name
postcode	String / null	Postal code or ZIP code
osmType	String / null	OpenStreetMap object type -- "node", "way", or "relation"
osmId	Number / null	Unique OpenStreetMap object identifier
placeType	String / null	Place classification such as "house", "street", "city", "country"
importance	Number / null	Nominatim importance ranking score between 0 and 1
boundingBox	Array / null	Geographic bounding box as [south lat, north lat, west lon, east lon]
extractedAt	String	ISO 8601 timestamp of when the result was extracted

When a query cannot be resolved, all location fields are set to null while the query and extractedAt fields are always populated. This makes it straightforward to filter successes from failures in downstream processing.

---

Use cases

• Real estate analysis -- geocode property addresses to plot them on maps, calculate distances between listings, or enrich property datasets with GPS coordinates
• Logistics and delivery routing -- convert customer delivery addresses into coordinates for route optimization and distance calculations
• Lead enrichment -- add geographic coordinates to business contact lists for proximity-based sales targeting and territory mapping
• Data cleaning and normalization -- standardize messy address data by geocoding free-text addresses and extracting structured components (city, state, postcode)
• Store locator databases -- build store finder features by geocoding retail locations and storing their coordinates for nearest-store lookups
• Academic research -- geocode survey respondent locations, historical site addresses, or field study coordinates for spatial analysis and GIS mapping
• Event planning -- convert venue addresses to coordinates for generating maps, calculating travel times, and finding nearby hotels or restaurants
• IoT and sensor data -- reverse geocode GPS coordinates from tracking devices, fleet vehicles, or mobile apps into human-readable addresses
• Market research -- map competitor locations, analyze geographic distribution of customers, or identify underserved areas by geocoding address datasets

---

API & integrations

Python

from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run = client.actor("i4BCLB2eHbePe78aj").call(run_input={
    "mode": "forward",
    "queries": [
        "1600 Pennsylvania Ave, Washington DC",
        "221B Baker Street, London",
        "Champs-Elysees, Paris"
    ],
    "language": "en"
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"{item['query']} -> {item['latitude']}, {item['longitude']}")

JavaScript

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_API_TOKEN' });

const run = await client.actor('i4BCLB2eHbePe78aj').call({
    mode: 'forward',
    queries: [
        '1600 Pennsylvania Ave, Washington DC',
        '221B Baker Street, London',
        'Champs-Elysees, Paris',
    ],
    language: 'en',
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.log(`${item.query} -> ${item.latitude}, ${item.longitude}`);
});

cURL

curl -X POST "https://api.apify.com/v2/acts/i4BCLB2eHbePe78aj/runs?token=YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "forward",
    "queries": ["1600 Pennsylvania Ave, Washington DC", "Big Ben, London"],
    "language": "en"
  }'

Integration platforms

• Google Sheets -- export geocoded results directly to spreadsheets for mapping and visualization
• Zapier -- trigger geocoding runs and route results to 5,000+ connected apps
• Make (Integromat) -- build multi-step automation workflows with geocoded address data
• Webhooks -- receive HTTP notifications when geocoding runs complete for event-driven pipelines
• Slack / Email -- get notified of completed runs or failed lookups automatically
• Apify datasets API -- fetch results programmatically in JSON, CSV, XML, or Excel format from any language

---

How it works

The actor processes geocoding requests through the following pipeline:

1. Input validation -- the actor reads the input configuration and validates the selected mode, checking that queries are provided for forward mode or that matching latitude/longitude arrays exist for reverse mode.
2. Request construction -- for each item in the batch, the actor builds a Nominatim API request URL with the appropriate parameters (/search for forward, /reverse for reverse) including format, address detail, country code, and language settings.
3. Rate-limited execution -- requests are sent sequentially with a 1.1-second delay between each call. A custom User-Agent header identifies the actor to comply with Nominatim's terms of service.
4. Response parsing -- the Nominatim JSON response is parsed and mapped into a standardized 16-field output structure. The city field is intelligently resolved from city, town, village, or municipality depending on what Nominatim returns.
5. Null-safe fallback -- if a query returns no results or encounters an error, a result record is still created with the original query and all location fields set to null.
6. Dataset push -- all results are pushed to the Apify dataset in a single batch for efficient storage and retrieval.

Input Addresses          Nominatim API            Structured Output
+------------------+     +------------------+     +------------------+
| "Eiffel Tower"   | --> | /search?q=...    | --> | lat: 48.8584     |
| "Big Ben"        |     | format=jsonv2    |     | lon: 2.2945      |
| "Colosseum"      |     | addressdetails=1 |     | city: Paris      |
+------------------+     +------------------+     | country: France  |
        |                   1.1s delay              +------------------+
        |                 between each                      |
        v                   request                         v
  Batch Queue        Rate-Limited Fetch           Apify Dataset

---

Performance & cost

The actor runs on minimal resources since it only performs lightweight HTTP API calls with no browser rendering or HTML parsing.

Batch size	Estimated time	Estimated Apify cost	Nominatim API cost
10 addresses	~12 seconds	< $0.01	Free
50 addresses	~1 minute	< $0.01	Free
100 addresses	~2 minutes	$0.01 -- $0.02	Free
500 addresses	~9 minutes	$0.05 -- $0.08	Free
1,000 addresses	~18 minutes	$0.10 -- $0.15	Free

• Memory usage: 256 MB (minimum tier) is sufficient for all batch sizes
• Processing speed: ~1.1 seconds per address due to Nominatim's mandatory rate limit
• Cost driver: Apify compute time is the only cost; the Nominatim API itself is completely free
• Comparison: Google Maps Geocoding API charges $5.00 per 1,000 requests; this actor geocodes the same volume for approximately $0.10 in Apify compute

---

Limitations

• Rate limit of 1 request per second -- Nominatim enforces this strictly, so large batches (1,000+ addresses) will take 18+ minutes. This cannot be bypassed without hosting your own Nominatim instance.
• Single best result -- forward geocoding returns only the top-ranked result (limit=1). If the best match is incorrect, there is no way to retrieve alternative candidates.
• OpenStreetMap data coverage varies -- accuracy is excellent in North America, Europe, and major cities worldwide, but may be lower in rural or less-mapped regions of developing countries.
• No structured address input -- forward geocoding accepts free-text queries only. There is no option to provide separate fields for street, city, state, and country to improve matching precision.
• Address component language availability -- multi-language results depend on translations existing in OpenStreetMap. Less common languages may fall back to the local language of the location.
• No geocoding confidence score -- the importance field reflects the prominence of the place in OpenStreetMap, not the confidence of the match. There is no explicit match quality indicator.
• Sequential processing only -- due to the rate limit, requests are processed one at a time. Parallel geocoding is not supported by the public Nominatim instance.

---

Responsible use

• Respect Nominatim usage policies -- this actor complies with the Nominatim Usage Policy by enforcing rate limits and providing a descriptive User-Agent header. Do not attempt to bypass these limits.
• Attribute OpenStreetMap -- Nominatim data comes from OpenStreetMap contributors. If you display geocoded results publicly, include appropriate attribution as required by the ODbL license.
• Avoid excessive batch sizes -- while the actor handles rate limiting automatically, submitting extremely large batches (10,000+ addresses) places unnecessary load on the free public Nominatim infrastructure. For very large workloads, consider hosting your own Nominatim instance.
• Do not use for real-time applications -- the 1-second rate limit makes this unsuitable for user-facing real-time geocoding. Use it for batch processing and data enrichment workflows instead.
• Handle personal data responsibly -- if you are geocoding personal addresses, ensure compliance with applicable data protection regulations (GDPR, CCPA, etc.) regarding the processing and storage of location data.

---

FAQ

Q: Is the Nominatim geocoding API free to use? A: Yes. Nominatim is a free, open-source geocoding service powered by OpenStreetMap data. There are no API keys, subscriptions, or per-request charges. The only cost is Apify compute time for running the actor.

Q: How accurate is Nominatim compared to Google Maps Geocoding? A: For well-mapped regions (North America, Europe, Australia, major cities worldwide), Nominatim accuracy is comparable to commercial services. OpenStreetMap data is community-maintained and coverage varies by region. The importance field provides a rough indicator of place prominence, though it is not a match confidence score.

Q: Do I need an API key or account to use this actor? A: No. The Nominatim API requires no authentication. You only need an Apify account to run the actor. The actor handles all Nominatim communication including the required User-Agent header.

Q: What happens if an address cannot be found? A: The actor returns a result record with the original query preserved in the query field and all location fields (latitude, longitude, displayName, city, etc.) set to null. This makes it easy to identify and retry failed lookups.

Q: Can I geocode addresses in any country? A: Yes. OpenStreetMap has global coverage spanning 200+ countries. Use the countryCode parameter with an ISO 3166-1 alpha-2 code (e.g., "US", "GB", "JP", "BR", "IN") to restrict results and improve accuracy for a specific country.

Q: How many addresses can I geocode in one run? A: There is no hard limit on batch size. Processing time scales linearly at approximately 1.1 seconds per address. A batch of 100 addresses takes about 2 minutes; 1,000 addresses takes about 18 minutes. For batches larger than 1,000, consider splitting across multiple scheduled runs.

Q: Can I get results in languages other than English? A: Yes. Set the language parameter to any ISO 639-1 language code (e.g., "de" for German, "fr" for French, "ja" for Japanese, "ar" for Arabic). Address components will be returned in the specified language when translations exist in OpenStreetMap.

Q: What is the difference between forward and reverse geocoding? A: Forward geocoding converts a text address (like "1600 Pennsylvania Ave, Washington DC") into GPS coordinates (38.8977, -77.0365). Reverse geocoding does the opposite -- it takes GPS coordinates and returns the corresponding street address.

Q: Why does the actor take over a second per address? A: The public Nominatim API enforces a strict rate limit of 1 request per second. The actor waits 1.1 seconds between requests to ensure compliance and prevent your requests from being blocked. This is a limitation of the free public service, not the actor itself.

Q: Can I use the results for commercial purposes? A: Yes. OpenStreetMap data is licensed under the Open Database License (ODbL), which permits commercial use provided you give appropriate attribution and share any modifications to the data itself. Geocoding results derived from the data can be used freely.

Q: What coordinate format does reverse geocoding expect? A: Latitudes and longitudes should be provided as decimal degree strings (e.g., "48.8584" for latitude, "2.2945" for longitude). Use at least 4 decimal places for street-level accuracy. The latitudes and longitudes lists must be the same length.

Q: How does the actor handle errors or API failures? A: If a Nominatim request fails due to a network error or API issue, the actor logs the error and returns a result with null location fields for that query. The batch continues processing remaining items. No data is lost -- you can identify failures by checking for null latitude values.

---

Related actors

Actor	Description
OpenStreetMap POI Search	Search for points of interest (restaurants, shops, parks, hospitals) near geocoded coordinates using OpenStreetMap data
Open Charge Map EV Stations	Find electric vehicle charging stations near any geocoded location worldwide
Weather Forecast Search	Get weather forecasts and current conditions for geocoded GPS coordinates
IP Geolocation Lookup	Convert IP addresses to geographic locations -- a complementary approach to address-based geocoding
REST Countries Data Search	Look up country details including ISO codes, currencies, and languages to pair with geocoded country results