Method: resolveNames

Resolves a list of place names (or addresses) to specific geospatial entities (e.g., places) on Google Maps.

HTTP request

POST https://mapstools.googleapis.com/v1alpha:resolveNames

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "queries": [
    {
      object (LocationQuery)
    }
  ],
  "locationBias": {
    object (LocationBias)
  },
  "regionCode": string
}
Fields
queries[]

object (LocationQuery)

Required. A list of location queries to be resolved. You may specify up to 20 queries.
locationBias

object (LocationBias)

Optional. An optional region to bias the resolution results. If specified, the resolution results will be biased towards the entities that are closer to this region. Including locationBias or regionCode often provides better results by narrowing the search space.

If both locationBias and regionCode are specified, locationBias takes precedence over regionCode.
regionCode

string

Optional. An optional region code to bias the resolution results. If specified, the resolution results will be biased towards the entities that are in or near the specified region. This should be a CLDR region code. For example, "US" or "CA". Including locationBias or regionCode often provides better results by narrowing the search space.

If both locationBias and regionCode are specified, locationBias takes precedence over regionCode.

Response body

Response message for v1alpha.resolveNames.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "results": [
    {
      object (Result)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  }
}
Fields
results[]

object (Result)

Output only. The list of resolved entities from the location queries. Guaranteed to map 1:1 with the request queries indices. An empty string at index i indicates the resolution failed for that query. If the resolution failed, please check the failedRequests field for the error status.
failedRequests

map (key: integer, value: object (Status))

Output only. A map communicating partial failures. The key is the index of the failed request in the queries field. The value is the error status detailing why the resolution failed.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/maps-platform.mapstools
  • https://www.googleapis.com/auth/cloud-platform.read-only

LocationQuery

A location query represents a specific location entity that can be resolved with Google Maps. Currently, only place names and addresses are supported as location queries.

JSON representation 
{
  "text": string
}
Fields
text

string

Required. The text query to resolve to a specific geospatial entity on Google Maps, such as a place or an address. The more specific the query, the more accurate the resolution. For example, "San Francisco", "Googleplex, Mountain View, CA", "1600 Amphitheatre Parkway, Mountain View, CA", or "Eiffel Tower, Paris". Queries must be a specific address or place name. General locations like a chain name (e.g. Starbucks) or a search query like "restaurants" are not supported.

LocationBias

The region to bias the resolution results to.

JSON representation 
{

  // Union field type can be only one of the following:
  "viewport": {
    object (Viewport)
  }
  // End of list of possible types for union field type.
}
Fields
Union field type. The type of the location bias. type can be only one of the following:
viewport

object (Viewport)

A viewport defined by a bounding box.

Viewport

A latitude-longitude viewport, represented as two diagonally opposite low and high points. A viewport is considered a closed region, i.e. it includes its boundary. The latitude bounds must range between -90 to 90 degrees inclusive, and the longitude bounds must range between -180 to 180 degrees inclusive. Various cases include:

  • If low = high, the viewport consists of that single point.

  • If low.longitude > high.longitude, the longitude range is inverted (the viewport crosses the 180 degree longitude line).

  • If low.longitude = -180 degrees and high.longitude = 180 degrees, the viewport includes all longitudes.

  • If low.longitude = 180 degrees and high.longitude = -180 degrees, the longitude range is empty.

  • If low.latitude > high.latitude, the latitude range is empty.

Both low and high must be populated, and the represented box cannot be empty (as specified by the definitions above). An empty viewport will result in an error.

For example, this viewport fully encloses New York City:

{ "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } }

JSON representation 
{
  "low": {
    object (LatLng)
  },
  "high": {
    object (LatLng)
  }
}
Fields
low

object (LatLng)

Required. The low point of the viewport.
high

object (LatLng)

Required. The high point of the viewport.

LatLng

An object that represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, this object must conform to the WGS84 standard. Values must be within normalized ranges.

JSON representation 
{
  "latitude": number,
  "longitude": number
}
Fields
latitude

number

The latitude in degrees. It must be in the range [-90.0, +90.0].
longitude

number

The longitude in degrees. It must be in the range [-180.0, +180.0].

Result

A single resolved entity from a given location query, along with the confidence level of the resolution.

JSON representation 
{
  "entity": {
    object (Entity)
  },
  "confidence": enum (Confidence)
}
Fields
entity

object (Entity)

Output only. The resolved entity from the location query.
confidence

enum (Confidence)

Output only. The level of confidence for the resolution.

Confidence

The level of confidence for the resolution.

Enums
CONFIDENCE_UNSPECIFIED Default value. This value is unused.
MEDIUM Medium confidence indicates that the resolution is likely correct but there may be other candidates.
HIGH High confidence indicates that the resolution is correct and represents a specific geospatial entity (e.g., a specific place).