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)
  • Get suggestions when typing the address string for Locations By Text (Suggestions by Text)
  • 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).

Geocoding API vs Geocoding OSM API

  • Different data sources: Geocoding API is based on HERE data while Geocoding OSM API is based on OSM data.
  • Different APIs: The two APIs differ in input and return parameters.
  • Different concepts: OSM API only knows places while Geocoding API distinguishes between locations and places. OSM API returns places records which contain an address and can additionally have a name and category.

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. 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 exist in the map, with, among others, formatted addresses 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 or Locations by Text 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 or you can call the Locations by Text endpoint using the data returned by the Suggestions by Text endpoint.

Locations By Position versus Position Matching

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