Geocoding converts an address into coordinates, for example to show customer addresses on a map or to calculate distances. Reverse geocoding does the opposite and finds the address for a point, such as a GPS location from an app. Both use the same endpoint and return exactly one result, the best match.
Convert an address to coordinates
Pass the address in the address parameter, at most 256 characters. Optionally, restrict the search to one country with country and choose the language of the names with language (default de).
curl "https://api.flowdata.one/v1/maps/geocode?address=Alexanderplatz%201,%2010178%20Berlin&country=DE&language=en" \
-H "Authorization: Bearer fd_YOUR_KEY"
The address field of the response contains exactly one result:
{
"success": true,
"address": {
"lat": 52.521918,
"lng": 13.413215,
"full_address": "Alexanderplatz 1, 10178 Berlin, Germany",
"address_name": "Alexanderplatz 1",
"address_number": "1",
"street_name": "Alexanderplatz",
"postcode_name": "10178",
"locality_name": "Mitte",
"place_name": "Berlin",
"place_code": "BE",
"region_name": "Berlin",
"region_code": "BE",
"country_name": "Germany",
"country_code": "DE"
},
"attribution": "NOTICE: © 2026 ..."
}
The fields are the same as in the place search, plus place_code, a short code for the place. All fields are explained in How do I search for places and addresses with Maps?.
Convert coordinates to an address
To go the other way, send the two parameters lat (latitude, -90 to 90) and lng (longitude, -180 to 180) instead of address. As soon as both are set, the endpoint works in reverse.
curl "https://api.flowdata.one/v1/maps/geocode?lat=52.5219&lng=13.4132" \
-H "Authorization: Bearer fd_YOUR_KEY"
The response has the same format as above, with the address closest to the point.
When nothing is found
If Maps can't find a matching address, it returns HTTP 404:
{"success":false,"error":"No address data found for this address"}
For reverse geocoding the text is No address found for the specified coordinates. Typical causes are typos, a missing postal code, a wrong country code or coordinates pointing at water or open land.
If address, lat and lng are all missing, or you only pass one of the two coordinates, Maps answers with HTTP 422 and lists the affected fields under details:
{"success":false,"error":"Invalid parameters","details":{"address":["..."]}}
The key in details is the field name; the message text itself is in German at the moment.
Why do I get a neighboring address?
Maps remembers addresses it has already determined so that repeated requests are answered faster. With reverse geocoding, a known address in the immediate vicinity can therefore come back, such as the house next door. For maps, that's usually accurate enough. If you need the exact house number, ask the person to confirm the address.
For the same reason, names can arrive in a language other than the one in language if the address was previously determined in that other language.
Why don't short inputs give the right result?
Geocoding is meant for complete addresses. With very short or generic inputs like "Berlin" or "Main Street", you can get any result containing the term, for example some street address in Berlin. For reliable results:
- Provide street, house number, postal code and city.
- Set
countryif you know the country. - For search terms, place names and autocomplete, use the place search. It returns several results for you to choose from.
What does a request cost?
Geocoding is billed per 1,000 successful requests, at the same price in both directions. Responses with HTTP 404 or 422 and server errors are free. The amounts are on the pricing page, with details in Understanding FlowData prices.
Good to know
- Watch the names: geocoding uses the separate parameters
latandlng. In route calculation, you write coordinates aslongitude,latitudein a single value; see How do I calculate a route with Maps?. - The response includes a usage notice in the
attributionfield. The data must not be stored permanently.