FlowData

How do I search for places and addresses with Maps?

Published on 10. November 2026

The Maps place search finds addresses, streets, postal codes and places for a search term. It's useful for address autocomplete in an order form or for standardizing what your customers type. You get up to ten results with coordinates and neatly split address parts.

The request

The search is a GET to https://api.flowdata.one/v1/maps/search. Only the search term q is required.

curl "https://api.flowdata.one/v1/maps/search?q=Alexanderplatz%201%20Berlin&limit=5&country=DE&language=en" \
  -H "Authorization: Bearer fd_YOUR_KEY"

You can pass these parameters:

Parameter Meaning
q Search term, required, at most 256 characters. URL-encoded, so spaces become %20.
limit Number of results from 1 to 10. The default is 10.
country Two-letter country code such as DE, AT or CH. Limits the search to that country.
language Language of the names. The default is de.
proximity A point as longitude,latitude, for example 13.4050,52.5200. Results nearby are preferred.
types Limits the kind of results, for example address, street, postcode or place. Separate multiple values with commas.

For autocomplete, q, limit=5 and country=DE are usually all you need.

The response

{
  "success": true,
  "addresses": [
    {
      "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",
      "region_name": "Berlin",
      "region_code": "BE",
      "country_name": "Germany",
      "country_code": "DE"
    }
  ],
  "attribution": "NOTICE: © 2026 ... This response and the information it contains may not be retained."
}

The example is shortened; addresses usually contains several results. Each result has these fields:

  • lat, lng: latitude and longitude.
  • full_address: the complete, readable address for display.
  • address_name: street with house number.
  • street_name, address_number: street and house number separately.
  • postcode_name: postal code.
  • locality_name: district, if known.
  • place_name: city or municipality.
  • region_name, region_code: state and its code.
  • country_name, country_code: country and two-letter country code.

Fields that don't exist for a result are null. A postal code as a result, for example, has no street.

In what order do the results come?

Maps sorts results by completeness. Complete addresses with street, house number, postal code, place and country come first. Then come streets without a house number, then postal codes with a place, then places only, and finally results where only the country is known. For an address form, the first result is therefore usually the best match.

If nothing is found, you still get "success": true, but with an empty addresses list.

What does the attribution text mean?

Every successful response includes a usage notice in the attribution field. It says the data is subject to the terms of use and that the response must not be stored permanently. So display the results directly, or copy the address your customer picks into their order. Building your own address database from search results is not allowed.

When something goes wrong

If q is missing or a parameter is invalid, Maps answers with HTTP 422. details shows which field is the problem:

{"success":false,"error":"Invalid parameters","details":{"q":["..."]}}

The key in details is the field name; the message text itself is in German at the moment.

Other common pitfalls, such as swapped coordinates, are covered in Maps finds nothing or the wrong place: what can I do?.

What does a search cost?

The place search is billed per 1,000 successful requests. A search only counts if it returns at least one result. A search with an empty list and all errors are free. Responses from the cache count like any other successful response.

The amounts are on the pricing page, and the prices that apply to your team are in the dashboard under Billing. If your balance is too low, the API answers with HTTP 402. See Understanding FlowData prices for details.

Good to know

  • To see how many requests your integration makes and how many fail, go to Areas › Maps in the dashboard. Below that is the Log with every single request.
  • If you only need the coordinates of a known address, geocoding is more direct; see How do I convert an address to coordinates and back?.
  • Send the search from your server. For autocomplete in the browser, build a small endpoint of your own that passes the input on to Maps, so the key doesn't end up in the browser.
  • The full reference is in the API documentation.

Was this article helpful?

Back to Maps