Uber Developers

Geocode

GEThttps://api.uber.com/maps/beta/geocode

¶ Use Case

The Geocode endpoint returns a single location corresponding to the requested coordinate (reverse geocode) or address (forward geocoding). Geocoding is useful for converting a string address to a coordinate or a coordinate to a suggested location at that coordinate.

¶ Forward Geocode (address lookup)

Forward geocode, or simply geocoding, answers the question “Where am I?” by providing a single location that best matches a well formed address as the address lookup input string. Common use cases include a lookup of a full address, possibly received from a user through a public API, in order to get a coordinate, a latitude and longitude pair, as well as a place identifier for the matching location.

¶ Reverse Geocode (coordinate lookup)

Reverse geocode also answers the question “Where am I?” by providing a single location that best matches a coordinate, or latitude and longitude pair, as input. In general, reverse geocode should not be thought of as deterministic. Some examples of why this is true is to consider the z-index, or altitude, of a given location like a building which could produce different results that would all accurately match the coordinate. Another example might be when the coordinate is on a road segment and there are multiple locations that are equidistant. Callers should note that the higher the precision of the coordinate provided in the request, the more deterministic the result.

¶ Authorization

OAuth 2.0 Bearer token with the maps-apis scope.

¶ Request Parameters

¶ Forward Geocode (address lookup)

Name	Type	Description	Required?
`address`	string	A full, well-formatted address to query.	Yes
`locale`	string	The preferred language of the response. For example, the string “en-US”. This should follow the BCP47 standards.	No
`address_latitude`	double	The location of the place to search for.	No
`address_latitude`	double	The location of the place to search for.	No
`country_code`	string	ISO2 two character code representing a country to filter the lookup request. For example, the strings “US” or “BE”.	No

¶ Reverse Geocode (address lookup)

Name	Type	Description	Required?
`latitude`	double	The location of the place to search for.	Yes
`latitude`	double	The location of the place to search for.	Yes
`locale`	string	The preferred language of the response. For example, the string “en-US”. This should follow the BCP47 standards.	No

¶ Example Request

¶ Forward Geocode (address lookup)

 curl -X GET \
  -H "authorization: Bearer $UBER_TOKEN" \
  -H 'content-type: application/json' \
  https://$api_url/maps/beta/geocode?locale=en-US&query=555%20E%20El%20Camino%20Real,%20Sunnyvale,%20CA%2094087-1942,%20US | jq .

¶ Reverse Geocode (coordinate lookup)

 curl -X GET \
  -H "authorization: Bearer $UBER_TOKEN" \
  -H 'content-type: application/json' \
  https://$api_url/maps/beta/geocode?locale=en-USlatitude=41.85093847620449&longitude=12.48378041824863 | jq .

¶ Response body parameters

Name	Type	Description	Required?
`entity.id`	string	The unique identifier for the suggested location	Yes
`entity.location`	object	The location data for the place	Yes
`entity.location.name`	string	The name of the suggested location	No
`entity.location.address`	string	The full address for the suggested location	Yes
`entity.location.locale`	string	The locale used for the response	Yes
`entity.location.categories`	string	The list of categories the place belong to (i.e. Restaurant)	No
`entity.location.coordinate`	object	The physical location for the place	Yes
`entity.location.address_components`	array	The list of single components for the address	Yes
`entity.location.distanceMeters`	long	The distance, in meters from the input location, if one was supplied	No

For an overview of available address components, refer to Address Components

For an overview of available categories, refer to Categories

Status-code: 200 OK

{
  "entity": {
    "id": "u01:01:39c69a59-d4d5-6c3c-5841-67a8c27fe3f6",
    "location": {
      "address": "Via Ernesto Murolo 7, 00145 Rome",
      "locale": "en-US",
      "categories": [
        "street_address",
        "addressPoint"
      ],
      "coordinate": {
        "latitude": 41.850871,
        "longitude": 12.4838982
      },
      "address_components": [
        {
          "name": "7",
          "type": "HOUSE_NUMBER"
        },
        {
          "name": "Via Ernesto Murolo",
          "type": "STREET_NAME"
        },
        {
          "name": "00145",
          "abbreviation": "00145",
          "type": "POSTAL_CODE"
        },
        {
          "name": "IT",
          "type": "COUNTRY"
        },
        {
          "name": "12",
          "type": "FEDERATED_STATE"
        },
        {
          "name": "Roma",
          "type": "CITY"
        }
      ]
    }
  }
}