# Geocoding Endpoint

Endpoint: GET /geocode
Version: 1.0.0
Security: api_key

## Query parameters:

  - `q` (string)
    A textual description of the address you are looking for. Required for forward geocoding. Note that the  geocoding provider does prefix searches preferable for "autocomplete" use cases, but
may lead to sub-optimal results if used without user interaction. See e.g.  as an appropriate alternative for less interactive use cases.

  - `locale` (string)
    Display the search results for the specified locale. Currently French (fr), English (en) and German (de) are explicitly supported. Otherwise leave the locale empty.

  - `limit` (integer)
    Specify the maximum number of results to return

  - `reverse` (boolean)
    It is  to be  if you want to do a reverse geocoding request. If it is ,  must be defined as well, and  must not be used.

  - `debug` (boolean)
    If , the output will be formatted.

  - `point` (string)
    _Forward geocoding_: The location bias in the format 'latitude,longitude' e.g. point=45.93272,11.58803. _Reverse geocoding_: The location to find amenities, cities.

  - `provider` (string)
    The provider parameter is currently under development and can fall back to  at any time.
The intend is to provide alternatives to our default geocoder. Each provider has its own strenghts and might fit better for certain scenarios, so it's worth to compare the different providers.
To try it append the parameter to the URL like ,
the result structure should be identical in all cases - if not, please report this back to us.
Keep in mind that some providers do not support certain parameters or don't return some fields, for example  and  are not supported by every geocoding provider.
If you would like to use additional parameters of one of the providers, but it's not available for the GraphHopper Geocoding API, yet? Please contact us.

The credit costs can be different for all providers - see here for more information about it.

Currently, only the default provider and gisgraphy support autocompletion of partial search strings.

All providers support normal "forward" geocoding and reverse geocoding via .

#### Default ()

This provider returns results of our internal geocoding engine. It is best suited for use cases with user interaction as it does prefix searches required for an "autocomplete" use case
(a user types an address into a search field).

In addition to the above documented parameters the following parameters are possible:

*  - you can filter  or exclude places with certain OpenStreetMap tags . E.g.  or just the key . To exclude multiple tags you add multiple  parameters.
*  - describes how much the prominence of a result should still be taken into account. Sensible values go from 0.0 (ignore prominence almost completely) to 1.0 (prominence has approximately the same influence as the location). The default is 0.2.
*  - describes the radius around the center to focus on. This is a number that should correspond roughly to the map zoom parameter of a corresponding map. The default is zoom=16.
*  - the expected format is . This requires reverse=false.
*  - the search radius in km for the reverse search. This requires reverse=true.

#### Nominatim ()

The GraphHopper Directions API uses a commercially hosted Nominatim geocoder (hosted by OpenCageData). It is best suited for use cases without or less user interaction
like batch processing or detailed location data retrieval. It is not suited for "autocomplete".

In addition to the above documented parameters we currently support the following parameters:

* countrycode - The country code is a two letter code as defined by the ISO 3166-1 Alpha 2 standard. E.g. gb for the United Kingdom, fr for France, us for United States.
* bounds - the expected format is 

#### Gisgraphy ()

This provider returns results from the Gisgraphy geocoder which you can try here.

 The  parameter is not supported. Gisgraphy does not return OSM tags or an extent.

Gisgraphy has a special autocomplete API, which you can use by adding  (does not work with ). The autocomplete API is optimized on predicting text input, but returns less information.

In addition to the above documented parameters Gisgraphy allows to use the following parameters, which can be used as documented here:

*  - radius in meters
*  - restrict search for the specified country. The value must be the ISO 3166 Alpha 2 code of the country.

#### OpenCage Data ()

This provider returns results from the OpenCageData geocoder which you can try here.
The difference to the  provider is that other geocoders might be used under the hood.

In addition to the above documented parameters OpenCage Data allows to use the following parameters, which can be used as documented here:

* countrycode - The country code is a two letter code as defined by the ISO 3166-1 Alpha 2 standard. E.g. gb for the United Kingdom, fr for France, us for United States. 
* bounds - the expected format is

## Response 200 fields (application/json):

  - `hits` (array)
    Example: [{"osm_id":240109189,"osm_type":"N","country":"Deutschland","osm_key":"place","city":"Berlin","osm_value":"city","postcode":"10117","name":"Berlin","point":{"lng":13.3888599,"lat":52.5170365}},{"osm_id":62422,"osm_type":"R","extent":[13.088345,52.6755087,13.7611609,52.33826],"country":"Deutschland","osm_key":"place","osm_value":"city","name":"Berlin","point":{"lng":13.4385964,"lat":52.5198535}},{"osm_id":120456814,"osm_type":"W","extent":[13.3906703,52.5200704,13.3948873,52.5175007],"country":"Deutschland","osm_key":"amenity","city":"Berlin","street":"Dorotheenstraße","osm_value":"university","postcode":"10117","name":"Humboldt-Universität zu Berlin","point":{"lng":13.393560493637775,"lat":52.51875685}},{"osm_id":6647,"osm_type":"R","extent":[13.3924346,52.5191829,13.3948768,52.517526],"country":"Deutschland","osm_key":"building","housenumber":"6","city":"Berlin","street":"Unter den Linden","osm_value":"yes","postcode":"10117","name":"Humboldt-Universität zu Berlin","point":{"lng":13.392908021752554,"lat":52.51840935}},{"osm_id":38862723,"osm_type":"W","extent":[13.2364563,52.5161915,13.2433375,52.5129557],"country":"Deutschland","osm_key":"leisure","housenumber":"3","city":"Berlin","street":"Olympischer Platz","osm_value":"stadium","postcode":"14053","name":"Olympiastadion Berlin","point":{"lng":13.239776301622072,"lat":52.5147077}},{"osm_id":583306346,"osm_type":"W","extent":[13.3739245,52.528547,13.3818019,52.5229778],"country":"Deutschland","osm_key":"amenity","city":"Berlin","street":"Hufelandweg","osm_value":"hospital","postcode":"10117","name":"Charité Universitätsmedizin Berlin","point":{"lng":13.377739577932736,"lat":52.52585125}},{"osm_id":180594,"osm_type":"R","extent":[13.3906159,52.5190301,13.3923847,52.5174089],"country":"Deutschland","osm_key":"amenity","housenumber":"8","city":"Berlin","street":"Unter den Linden","osm_value":"library","postcode":"10117","name":"Staatsbibliothek zu Berlin","point":{"lng":13.391516532100738,"lat":52.5182233}},{"osm_id":3856100103,"osm_type":"N","country":"Deutschland","osm_key":"railway","city":"Berlin","street":"Washingtonplatz","osm_value":"station","postcode":"10557","name":"Berlin Hauptbahnhof","point":{"lng":13.3696614,"lat":52.5249451}},{"osm_id":1078631331,"osm_type":"N","country":"Deutschland","osm_key":"historic","city":"Berlin","street":"Gertrud-Kolmar-Straße","osm_value":"battlefield","postcode":"10117","name":"Schlacht um Berlin","point":{"lng":13.3814231,"lat":52.5127537}},{"osm_id":1154556,"osm_type":"R","extent":[13.3807495,52.5083344,13.3822459,52.5074359],"country":"Deutschland","osm_key":"office","housenumber":"5","city":"Berlin","street":"Niederkirchnerstraße","osm_value":"government","postcode":"10117","name":"Abgeordnetenhaus von Berlin","point":{"lng":13.381504320489928,"lat":52.50786655}}]

  - `hits.point` (object)

  - `hits.point.lat` (number)
    Latitude

  - `hits.point.lng` (number)
    Longitude

  - `hits.osm_id` (string)
    The OSM ID of the entity

  - `hits.osm_type` (string)
    N = node, R = relation, W = way

  - `hits.osm_key` (string)
    The OSM key of the entity

  - `hits.name` (string)
    The name of the entity. Can be a boundary, POI, address, etc

  - `hits.country` (string)
    The country of the address

  - `hits.city` (string)
    The city of the address

  - `hits.state` (string)
    The state of the address

  - `hits.street` (string)
    The street of the address

  - `hits.housenumber` (string)
    The housenumber of the address

  - `hits.postcode` (string)
    The postcode of the address

  - `took` (number)
    in ms
    Example: 37