Search for content

Which Endpoints Are in the Geocoding API and Which One Should I Use?

The Geocoding API Offers the Following Services:

  • Find locations matching an address to get their geographic positions,
  • Get suggestions when filling out the input fields for Locations By Address (Suggestions by Address)
  • Find locations near a geographic position to get their addresses (Locations by Position).
  • Find places of certain categories near a geographic position to find their addresses and names (Places by Position).
  • Find places of certain categories in a given area to find their addresses and names (Places by Area). A corresponding use case would be a corridor search along a calculated route.
  • Find places of certain categories using a single search text to match their names (Places by Text).
  • List available place categories (Place Categories).

Locations versus Places

  • Locations consist of a postal address (like "10, Downing Street, London") and a geographic position. Use locations when you are mainly interested in the address but not so much in any services available there (e.g. when delivering).
  • Places additionally have a name (like "Presseshop Kiosk") and a category (like "Restaurant" or "Fueling Station"). Use places if you are interested in a specific service (e.g. like a restaurant or fueling station).

Locations by Text vs by Address

  • If you search by address, you pass the different fields of the address as separate strings. Use this if your data is available in that form, e.g. from a customer database.
  • If you search by text, all address fields are entered as one single string. Use this if your input is not split into fields.  

Locations vs Suggestions

  • If you call an endpoint returning Locations, the result will contain locations that exists in the map, with, among others, formatted address and coordinates.
  • If you call an endpoint returning Suggestions, the results will only be strings which are helpful to fill out a Locations by Address request. They may contain only partial addresses (e.g only a country, but no locality) and may not identify a unique location (e.g when there are several Localities of the same name).
  • To get a list of Locations, you can call the Location by Address endpoint using the data returned by the Suggestions by Address endpoint.

Locations By Position versus Position Matching

There is a separate concept which compares these two endpoints in detail.