Typing an address into a search box and getting a pin back feels instant. Behind that pin, though, the geocoder has guessed which of many possible matches you meant, how precise it could be, and what to do with the parts of the address it did not recognize. Good geocoding is mostly about giving the geocoder unambiguous input and checking its guesses afterwards. This guide walks through the process step by step. If you are new to the idea, What Is Geocoding? covers the basics.
1. Clean and standardize the input
Geocoders match text against a database of named places, streets and house numbers. Anything that is not part of that vocabulary adds noise. Before you send a query:
- Trim and collapse whitespace, remove stray punctuation, and fix obvious encoding damage (for example
Münchenshould beMünchen). - Remove unit-level detail such as flat, suite, floor or "c/o" lines. Open geocoders generally resolve to a building or street at best, and unit numbers often confuse the match. Keep them in your own record, just not in the query.
- Expand or normalize abbreviations consistently. "St" may mean Street or Saint, and "Rd", "Blvd" and "Bldg" vary by data source. Expanding them often helps, but test against your own data.
- Drop free-text directions such as "opposite the mall" or "near the mosque". They are useful to a driver but meaningless to a database lookup.
- Split combined fields where a spreadsheet has merged city and postcode into one column.
Example: " flat 12, bldg 5 ,al wasl rd , dubai " becomes Al Wasl Road, Dubai, United Arab Emirates, with "Flat 12, Building 5" kept in a separate field for your own use. In many cities a building name or a nearby landmark geocodes better than a street number. That is especially true where street numbering is sparse in the map data.
2. Always include the country
Place names repeat around the world. There are cities called Paris in France, Texas and Ontario, and Springfield in more than a dozen US states. A query without a country forces the geocoder to rank candidates globally, and the most prominent one wins, which is often not the one you meant. Add the country name to free-form queries, and where the API supports it, restrict results with a country-code filter. In Nominatim, for example, this is the countrycodes parameter.
Adding the region or city does the same job one level down. "Main Street" alone is hopeless; "Main Street, Springfield, Illinois, USA" is answerable.
3. Structured or free-form query?
There are two ways to ask:
- Free-form
- One string, such as
q=10 Downing Street, London, UK. Convenient, tolerant of odd formatting, and the right choice for user-typed searches. - Structured
- Separate fields for street, city, state, postcode and country. Nominatim itself accepts
street,city,county,state,countryandpostalcode. Structured queries remove ambiguity about which part is which, so they usually work better when your data already sits in columns.
Check the API documentation of whichever service you use for the parameters it accepts. Our own API examples below use the free-form q parameter.
4. Choose a geocoder
The right service depends on volume, coverage and licensing more than on any single accuracy number:
- Coverage of your area. OpenStreetMap address coverage is excellent in some countries and patchy in others. Test a sample of your real addresses before committing. Our guide to geocoding with OpenStreetMap covers the strengths and gaps.
- License of the results. Some providers restrict storing results or showing them on third-party maps. OpenStreetMap-derived results are under the ODbL, which allows storage and reuse with attribution and share-alike conditions.
- Volume and rate limits. A handful of lookups a day and a nightly job of 200,000 rows are different problems, as covered below.
For ad-hoc lookups you can use the address to coordinates tool. For applications, the JSON API returns the same data.
Example: calling the OpenGeocoder API
curl -G "https://opengeocoder.net/api/v1/geocode" \
--data-urlencode "q=Burj Khalifa, Dubai, United Arab Emirates"
An illustrative response, with values shortened:
{
"query": "Burj Khalifa, Dubai, United Arab Emirates",
"results": [
{
"lat": 25.1972,
"lon": 55.2742,
"display_name": "Burj Khalifa, Downtown Dubai, Dubai, United Arab Emirates",
"bbox": [55.2732, 25.1962, 55.2752, 25.1982],
"type": "building",
"importance": 0.6,
"source": "openstreetmap"
}
],
"attribution": "© OpenStreetMap contributors",
"licence": "ODbL-1.0"
}
In Python:
import requests
resp = requests.get(
"https://opengeocoder.net/api/v1/geocode",
params={"q": "Burj Khalifa, Dubai, United Arab Emirates"},
headers={"User-Agent": "my-app/1.0 (ops@example.com)"},
timeout=10,
)
resp.raise_for_status()
data = resp.json()
best = data["results"][0] if data["results"] else None
Note that bbox here is ordered [west, south, east, north], the same order as GeoJSON. Nominatim's own raw boundingbox field uses a different order (south, north, west, east), so check which you are reading. The bounding boxes guide explains the conventions.
5. Interpret the results
Do not just take the first coordinate. Read the fields that tell you what was matched:
- Type (and class or category). A result of type
houseorbuildingmeans an address-level match. A result of typeresidentialortertiarymeans a road was matched, but not the house number.suburb,cityoradministrativemeans the geocoder fell back to an area, and the coordinate is just a representative point inside it. Treat these levels very differently downstream. - Importance. A relative ranking score that reflects how prominent a place is. Use it to compare candidates for the same query, not as a confidence percentage, and not across different queries.
- Bounding box. The extent of the matched feature. A box a few meters across indicates a precise match. A box spanning several kilometers means your "address" resolved to a district or a city. Bbox size is one of the most reliable quick checks of match precision.
- Display name. Read it. If you asked for a street in Dubai and the display name ends in a different emirate or country, the match is wrong regardless of its score.
6. Handle no-match and multiple matches
No results: loop back and relax the query step by step. Correct spelling, remove the house number, try an alternative street name or a landmark, or switch between structured and free-form. Language matters too: a place may be mapped under its local-language name. If a cleaned query still fails, flag the record for manual review rather than guessing. A record with no coordinate is better than one with a confidently wrong coordinate.
Multiple results: filter by country and region first, then by type (prefer address-level over area-level). If several plausible candidates remain, an interactive app should show them to the user, as our place search does with type and disambiguation details. A batch process should record the ambiguity instead of silently picking the first.
7. Validate on a map
For any dataset that matters, plot the results. Outliers stand out immediately: a customer in the sea, a cluster of points on a city centroid, or a single address on the wrong continent from swapped latitude and longitude (see Latitude and Longitude Explained). Spot-check a random sample against an independent source, and use reverse geocoding on suspicious points to see what is actually at that location.
Batch geocoding: respect the limits
Shared, free geocoding services are not built for bulk jobs. The public Nominatim service's usage policy sets an absolute maximum of one request per second, requires an identifying User-Agent or Referer, asks applications to cache results, and discourages large-scale bulk geocoding.
To be plain about our own service: OpenGeocoder does not offer bulk geocoding. The API is rate-limited, fair-use and has no SLA. It suits interactive lookups and modest application traffic, not geocoding a whole customer database. For bulk or recurring jobs, you have two sound options:
- Self-host Nominatim. It is open-source software, with installation documentation, and you can import only the countries you need. Your own instance has no third-party rate limit.
- Use a commercial geocoding provider whose terms explicitly allow your volume and your intended storage and display of results.
Whichever you choose, deduplicate addresses before you geocode, cache every result, and never re-query an address you have already resolved unless the source data has changed.
8. Store results with provenance
A coordinate without provenance cannot be audited, refreshed or legally reused. Store alongside each result:
| Field | Example | Why |
|---|---|---|
| Original input | flat 12, bldg 5, al wasl rd | Reproduce or re-run the lookup |
| Query sent | Al Wasl Road, Dubai, United Arab Emirates | Debug cleaning rules |
| lat, lon | 25.1972, 55.2742 | The result (WGS84) |
| Match type, bbox | building, 4 numbers | Precision of the match |
| Source | openstreetmap via opengeocoder.net | Know where it came from |
| Timestamp | 2026-11-20T09:15:00Z | Map data changes; refresh old results |
| License and attribution | ODbL-1.0, © OpenStreetMap contributors | Meet license obligations |
For OpenStreetMap-derived results, the OpenStreetMap copyright page explains the attribution requirement ("© OpenStreetMap contributors") and the ODbL terms that apply when you publish or share a database containing that data. Display the attribution wherever you show the results publicly.
Geocoding checklist
- Clean the input: whitespace, encoding, abbreviations, unit numbers removed.
- Include the country, and restrict by country code where supported.
- Use structured queries when your data is already in columns.
- Check type, importance, bbox size and display name, not just the coordinate.
- Loop failed queries through simplification; flag rather than guess.
- Plot results and spot-check a sample.
- Respect rate limits; self-host or use a commercial provider for bulk work.
- Store source, timestamp, license and attribution with every coordinate.