Geocoding
Resolve a coordinate pair to the nearest address and place, or an address to its coordinates.
Overview
Geocoding puts a name to a point on the earth; reverse geocoding does the opposite. Both directions are the same question asked from opposite ends, so one field and one endpoint take both: anything that reads as two numbers is treated as a coordinate, everything else as something written.
Answers come from an index of OpenStreetMap data held on this server. Nothing you look up is forwarded to a geocoding service.
Web interface
One field, and Enter to look up. The dice fills it with a random example. There is no map on the page, deliberately; see Privacy.
A reverse lookup answers with two blocks, the nearest address and the nearest named place, each with the distance to the point asked about. Clicking a row in the list of matches puts its coordinates in the field and asks the reverse question about that point.
What the field accepts
| Typed | Read as |
|---|---|
52.5163, 13.3777 | latitude and longitude, in that order |
52.5163 13.3777, 52.5163;13.3777 | the same. A comma, a semicolon or a space all separate the two |
48.8584° 2.2945° | the same. Degree signs are ignored |
Pariser Platz 1, Berlin | street, house number and place, number last as most of Europe writes it |
350 5th Avenue, New York | the same, number first as North America writes it |
Pariser Platz, Berlin | a street in a place, without a number |
Karlsruhe | a place. Without a comma the whole line is a place name |
The part after the last comma is always the place to search in. A house number is a run of digits at
either end of what is left. At the front it may carry at most one letter, because 5th Avenue,
1st Street and 2nd Avenue begin with a digit and are street names, not numbers.
Spelling need not be exact: Hoeninger Weg, Köln finds Höninger Weg, and
Hauptstr finds Hauptstraße. Latitude outside ±90 or longitude outside ±180 is
not a coordinate and is searched as text instead.
Coordinates to address
The answer always carries both the nearest address and the nearest named place, with the distance to each. That is not redundancy. In a city the address is the answer; far from anything mapped it is not, and the metres are what say which case you are in.
| Distance | What it means |
|---|---|
| under 50 m | the address is the building you pointed at |
| 50 to 500 m | the right street or block, not necessarily the right door |
| over 500 m | nothing is mapped nearby. The named place is the better answer |
A point in the middle of the Atlantic returns an address 405 km away and a hamlet in the Azores. Both are correct and both distances say not to use them.
Address to coordinates
Street names are matched by trigram similarity against a table that holds each street once per place, so a misspelling still finds its street. Results are ranked by that similarity, then by whether the match is a place or a street, then by the kind of place, then by how many addresses a street carries. A city therefore beats a hamlet of the same name, and a long street beats a cul-de-sac.
When a house number was given, addresses lists every address that carries it on a
street whose name is a spelling of the one typed, in ranked order.
1600 Pennsylvania Avenue, Washington returns two, on different arms of the same avenue. Nothing
here knows which was meant, so nothing here chooses.
A street only counts as a spelling of what was typed when one name begins with the other, so
Pennsylvania Avenue reaches Pennsylvania Avenue NW but a Prager Platz stays out of an
answer about Pariser Platz.
URL parameters
| URL | Opens with |
|---|---|
/lookup/geo | an empty field |
/lookup/geo/52.5163,13.3777 | that coordinate, looked up |
/lookup/geo/Pariser%20Platz%201,%20Berlin | that address, looked up |
Everything after /lookup/geo/ is the query, so a comma, a dot or a slash in a street name cannot
cut it in half. Spaces have to be percent encoded.
API
| Method | Endpoint |
|---|---|
GET | https://api.troubleshooting.tools/v1/lookup/geo/{query} |
The query is the same line the field takes, percent encoded. The answer is JSON on one line with a
type of reverse or forward.
| Field | In | What it holds |
|---|---|---|
query | both | how the input was read: the coordinate pair, or the street, house number and place it was split into |
address | reverse | the nearest address, with distance_m |
place | reverse | the nearest named place, with distance_m |
addresses | forward | every address carrying the house number, ranked. Empty when no number was given or none was found |
results | forward | matching streets and places, each with kind, score and coordinates |
limit as a query parameter caps the number of results between 1 and 10; the default is 5.
Errors
| Status | When |
|---|---|
400 | the query is empty, or longer than 200 characters |
429 | the rate limit, with Retry-After and retryAfter in seconds |
500 | the lookup failed |
503 | the index is unavailable, which is what a rebuild looks like from outside |
A query that simply matches nothing is not an error. It answers 200 with empty
results.
Rate limits
60 lookups per minute per address, answered with 429 and
Retry-After beyond that.
The limit exists to keep the index from being walked systematically, which the OpenStreetMap usage policy forbids. If you need the data in bulk, take the planet file.
The data
Built from the OpenStreetMap planet file, filtered to objects carrying addr:street or
addr:housenumber and to settlements tagged place. An address on a building outline is
reduced to the centre of that outline.
Rebuilt quarterly, on the eighth of January, April, July and October. The old index answers throughout the rebuild and is replaced in a single step at the end, so there is no window in which the tool answers from half an index.
Coverage is uneven, and that decides how good an answer is. Some countries are mapped house by house and others are not mapped that way at all.
What this does not do: rank by fame or population beyond preferring a city to a hamlet of the same name, or search while you type.
Data © OpenStreetMap contributors, available under the Open Database License.
Privacy
What you type is answered on this server and is never sent to a geocoding service. There is no third party in the request at all.
There is no map on the page, and that is the reason. A map makes your browser fetch tiles directly from whoever serves them, which hands that party your address along with the request for them. A tool whose whole argument is that nothing is forwarded cannot end by forwarding the one thing that matters.
The rate limit counts against an HMAC of your address, not the address, so the file it keeps holds no record of who asked. Queries are logged as any other API call is, for the usage figures the dashboard shows.