azure.maps.search.operations package

class azure.maps.search.operations.SearchOperations(*args, **kwargs)[source]

Warning

DO NOT instantiate this class directly.

Instead, you should access the following operations through MapsSearchClient’s search attribute.

get_geocoding(*, top: int = 5, query: str | None = None, address_line: str | None = None, country_region: str | None = None, bbox: List[float] | None = None, view: str | None = None, coordinates: List[float] | None = None, admin_district: str | None = None, admin_district2: str | None = None, admin_district3: str | None = None, locality: str | None = None, postal_code: str | None = None, **kwargs: Any) → MutableMapping[str, Any][source]

Use to get longitude and latitude coordinates of a street address or name of a place.

The Get Geocoding API is an HTTP GET request that returns the longitude and latitude coordinates of the location being searched.

In many cases, the complete search service might be too much, for instance if you are only interested in traditional geocoding. Search can also be accessed for address look up exclusively. The geocoding is performed by hitting the geocoding endpoint with just the address or partial address in question. The geocoding search index will be queried for everything above the street level data. No Point of Interest (POIs) will be returned. Note that the geocoder is very tolerant of typos and incomplete addresses. It will also handle everything from exact street addresses or street or intersections as well as higher level geographies such as city centers, counties and states. The response also returns detailed address properties such as street, postal code, municipality, and country/region information.

Keyword Arguments:

  • top (int) – Maximum number of responses that will be returned. Default: 5, minimum: 1 and maximum: 20. Default value is 5.

  • query (str) – A string that contains information about a location, such as an address or landmark name. Default value is None.

  • address_line (str) –

    The official street line of an address relative to the area, as specified by the locality, or postalCode, properties. Typical use of this element would be to provide a street address or any official address.

    If query is given, should not use this parameter.. Default value is None.

  • country_region (str) –

    Signal for the geocoding result to an ISO 3166-1 Alpha-2 region/country code that is specified e.g. FR./

    If query is given, should not use this parameter.. Default value is None.

  • bbox (list[float]) –

    A rectangular area on the earth defined as a bounding box object. The sides of the rectangles are defined by longitude and latitude values. When you specify this parameter, the geographical area is taken into account when computing the results of a location query.

    Example: lon1,lat1,lon2,lat2. Default value is None.

  • view (str) –

    A string that represents an ISO 3166-1 Alpha-2 region/country code. This will alter Geopolitical disputed borders and labels to align with the specified user region. By default, the View parameter is set to “Auto” even if you haven’t defined it in the request.

    Please refer to Supported Views for details and to see the available Views. Default value is None.

  • coordinates (list[float]) – A point on the earth specified as a longitude and latitude. When you specify this parameter, the user’s location is taken into account and the results returned may be more relevant to the user. Example: &coordinates=lon,lat. Default value is None.

  • admin_district (str) –

    The country subdivision portion of an address, such as WA.

    If query is given, should not use this parameter.. Default value is None.

  • admin_district2 (str) –

    The county for the structured address, such as King.

    If query is given, should not use this parameter.. Default value is None.

  • admin_district3 (str) –

    The named area for the structured address.

    If query is given, should not use this parameter.. Default value is None.

  • locality (str) –

    The locality portion of an address, such as Seattle.

    If query is given, should not use this parameter.. Default value is None.

  • postal_code (str) –

    The postal code portion of an address.

    If query is given, should not use this parameter.. Default value is None.

Returns:

JSON object

Return type:

JSON

Raises:

HttpResponseError –

get_geocoding_batch(body: JSON, *, content_type: str = 'application/json', **kwargs: Any) → JSON[source]
get_geocoding_batch(body: IO[bytes], *, content_type: str = 'application/json', **kwargs: Any) → JSON

Use to send a batch of queries to the Geocoding API in a single request.

The Get Geocoding Batch API is an HTTP POST request that sends batches of up to 100 queries to the Geocoding API in a single request.

Submit Synchronous Batch Request

The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to 100 for this API.

POST Body for Batch Request

To send the geocoding queries you will use a POST request where the request body will contain the batchItems array in json format and the Content-Type header will be set to application/json. Here’s a sample request body containing 2 geocoding queries:

A geocoding batchItem object can accept any of the supported geocoding URI parameters.

The batch should contain at least 1 query.

Batch Response Model

The batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequests i.e. queries which were executed successfully. The batch response also includes a batchItems array which contains a response for each and every query in the batch request. The batchItems will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types:

  • GeocodingResponse - If the query completed successfully.

  • Error - If the query failed. The response will contain a code and a message in this case.

param body:

The list of address geocoding queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query. Is either a JSON type or a IO[bytes] type. Required.

type body:

JSON or IO[bytes]

return:

JSON object

rtype:

JSON

raises ~azure.core.exceptions.HttpResponseError:

get_polygon(*, coordinates: List[float], view: str | None = None, result_type: str = 'countryRegion', resolution: str = 'medium', **kwargs: Any) → MutableMapping[str, Any][source]

Use to get polygon data of a geographical area shape such as a city or a country region.

The Get Polygon API is an HTTP GET request that supplies polygon data of a geographical area outline such as a city or a country region.

Keyword Arguments:

  • coordinates (list[float]) – A point on the earth specified as a longitude and latitude. Example: &coordinates=lon,lat. Required.

  • view (str) –

    A string that represents an ISO 3166-1 Alpha-2 region/country code. This will alter Geopolitical disputed borders and labels to align with the specified user region. By default, the View parameter is set to “Auto” even if you haven’t defined it in the request.

    Please refer to Supported Views for details and to see the available Views. Default value is None.

  • result_type (str) – The geopolitical concept to return a boundary for. If not specified, the default is countryRegion result type. Known values are: “countryRegion”, “adminDistrict”, “adminDistrict2”, “postalCode”, “postalCode2”, “postalCode3”, “postalCode4”, “neighborhood”, and “locality”. Default value is “countryRegion”.

  • resolution (str) – Resolution determines the amount of points to send back. If not specified, the default is medium resolution. Known values are: “small”, “medium”, “large”, and “huge”. Default value is “medium”.

Returns:

JSON object

Return type:

JSON

Raises:

HttpResponseError –

get_reverse_geocoding(*, coordinates: List[float], result_types: List[str] | None = None, view: str | None = None, **kwargs: Any) → MutableMapping[str, Any][source]

Use to get a street address and location info from longitude and latitude coordinates.

The Get Reverse Geocoding API is an HTTP GET request used to translate a coordinate (example: 37.786505, -122.3862) into a human understandable street address. Useful in tracking applications where you receive a GPS feed from the device or asset and wish to know the address associated with the coordinates. This endpoint will return address information for a given coordinate.

Keyword Arguments:

  • coordinates (list[float]) – The coordinates of the location that you want to reverse geocode. Example: &coordinates=lon,lat. Required.

  • result_types (list[str]) –

    Specify entity types that you want in the response. Only the types you specify will be returned. If the point cannot be mapped to the entity types you specify, no location information is returned in the response. Default value is all possible entities. A comma separated list of entity types selected from the following options.

    • Address

    • Neighborhood

    • PopulatedPlace

    • Postcode1

    • AdminDivision1

    • AdminDivision2

    • CountryRegion

    These entity types are ordered from the most specific entity to the least specific entity. When entities of more than one entity type are found, only the most specific entity is returned. For example, if you specify Address and AdminDistrict1 as entity types and entities were found for both types, only the Address entity information is returned in the response. Default value is None.

  • view (str) –

    A string that represents an ISO 3166-1 Alpha-2 region/country code. This will alter Geopolitical disputed borders and labels to align with the specified user region. By default, the View parameter is set to “Auto” even if you haven’t defined it in the request.

    Please refer to Supported Views for details and to see the available Views. Default value is None.

Returns:

JSON object

Return type:

JSON

Raises:

HttpResponseError –

get_reverse_geocoding_batch(body: JSON, *, content_type: str = 'application/json', **kwargs: Any) → JSON[source]
get_reverse_geocoding_batch(body: IO[bytes], *, content_type: str = 'application/json', **kwargs: Any) → JSON

Use to send a batch of queries to the Reverse Geocoding API in a single request.

The Get Reverse Geocoding Batch API is an HTTP POST request that sends batches of up to 100 queries to Reverse Geocoding API using a single request.

Submit Synchronous Batch Request

The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to 100 for this API.

POST Body for Batch Request

To send the reverse geocoding queries you will use a POST request where the request body will contain the batchItems array in json format and the Content-Type header will be set to application/json. Here’s a sample request body containing 2 reverse geocoding queries:

A reverse geocoding batchItem object can accept any of the supported reverse geocoding URI parameters.

The batch should contain at least 1 query.

Batch Response Model

The batch response contains a summary component that indicates the totalRequests that were part of the original batch request and successfulRequests i.e. queries which were executed successfully. The batch response also includes a batchItems array which contains a response for each and every query in the batch request. The batchItems will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types:

  • GeocodingResponse - If the query completed successfully.

  • Error - If the query failed. The response will contain a code and a message in this case.

param body:

The list of reverse geocoding queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query. Is either a JSON type or a IO[bytes] type. Required.

type body:

JSON or IO[bytes]

return:

JSON object

rtype:

JSON

raises ~azure.core.exceptions.HttpResponseError: