Addresses
A location can be given as an address instead of coordinates:
{ "address": "Herrengasse 16, 8010 Graz" }
The API turns it into coordinates with the Photon geocoder, which searches OpenStreetMap data. This page explains what is accepted, what is refused and why the rules are strict.
Why the API refuses rather than guesses
A free-text geocoder always answers with its best candidates, and the best candidate is often not the address that was asked for. Real answers from Photon in November 2026:
| Asked for | First candidate returned |
|---|---|
| Mariahilfer Straße 9999, 1070 Wien (no such number) | Mariahilfer Straße 55, 1060 Wien |
| Stephansplatz 1, 1010 Wien | The underground station "Stephansplatz"; the house was third |
| Mariahilferstr. 10, Wien | A heating company in Brunn am Gebirge |
| Hauptstraße 5 | A doctor's practice in Stuttgart |
A plan built on such a point looks perfectly normal and sends someone to the wrong place. So the API never takes the first candidate on trust. It fetches up to 20 and accepts one only if it agrees with the text that was sent.
What has to agree
A candidate is accepted when all three of these hold:
- House number. The candidate's house number appears in the address.
- Street. The candidate's street name appears in the address. For hamlets whose houses are numbered without street names, the name of the hamlet counts.
- Place. If the address contains a postcode, the candidate must have that postcode. If it contains none, it must name the candidate's town, district or municipality.
An address therefore needs a house number and a postcode or town.
"Hauptstraße 5" alone is not enough.
Spelling that is understood
| Variation | Example |
|---|---|
| Upper and lower case | herrengasse 16 graz |
| ß and ss, Straße and Strasse | Mariahilfer Strasse 100 |
| The abbreviation Str. | Mariahilferstr. 100, Mariahilfer Str. 100 |
| Street names written together or apart | Mariahilferstraße, Mariahilfer Straße |
| Umlauts as ae, oe, ue or left out | Schoenbrunner, Unterthurnau |
| Staircase and door after a slash | Linzer Gasse 20/3 means house 20 |
| A letter suffix written apart | Hauptplatz 10 a means 10a |
| Commas and their absence | Herrengasse 16 8010 Graz |
A different house number is never accepted as close enough: 10 is not 10a, and 9 is not "9-10".
Reasons an address is refused
The API reports every address it could not use in one response, each with a
reason:
reason | Meaning | What to do |
|---|---|---|
not_found | Neither the house nor the street is in the map. | Check the spelling, or whether the place is in the loaded region. |
house_number_not_found | The street exists in that place, but not this house number. | Send coordinates, or allow street precision (below). |
postcode_mismatch | House and street exist, but under another postcode. The message names the one found. | Correct the postcode. |
place_missing | The address has no postcode or town, and that street and number exist in more than one place. | Add the postcode. |
ambiguous | Several different places fit, for example the same address in two districts of one city. The message lists them. | Add the postcode. |
Street precision
OpenStreetMap does not contain every house number. For such addresses a request can opt in to a coarser match:
"options": { "address_precision": "street" }
The address is then located at a point on the street, provided street and place agree. The response marks it:
{ "owner": "stop shop", "address": "Mariahilfer Straße 9999, 1070 Wien",
"matched": "Mariahilfer Straße, 1070 Wien", "precision": "street", "location": { "lat": 48.19671, "lon": 16.34416 } }
On a long street that point can be more than a kilometre from the door, so show the precision to the planner and let them correct the position.
What the response tells you
Every address used comes back in geocoded with the address as the map
knows it, its coordinates and the precision. Show matched next to what the
user typed; a difference is the cheapest way for them to spot a mistake.
A location that is not spelled out, the end of a route that defaults to its start, is not listed a second time.