---
title: "Use to get ranked list of suggested entities based on a user's location and a partial query."
method: GET
path: "/geocode:autocomplete"
---

# Use to get ranked list of suggested entities based on a user's location and a partial query.

`GET /geocode:autocomplete`

Given a request with a user's location and a partial query that serves as the prefix of a full query string (referred to as a query prefix), the Azure Maps Autocomplete API returns a list of suggested entities that the user is most likely searching for. These entities are ranked from most to least likely.

## Query parameters

- `api-version` string, required
- `query` string, required
- `coordinates` number[]
- `bbox` number[]
- `top` integer
- `resultTypeGroups` string[]
- `resultTypes` string[]
- `view` string
- `countryRegion` string

## Headers

- `x-ms-client-id` string
- `Accept-Language` string

## Response `200`

The request has succeeded.

- AutocompleteResponse — The successful response body returned by `Get Autocomplete`. Encoded as a [`GeoJSON FeatureCollection`](https://www.rfc-editor.org/rfc/rfc7946) whose `features` array contains one `Feature` per autocomplete suggestion, ranked from most to least likely.
  - `type` 'FeatureCollection' — The `GeoJSON` object type used at the root of successful responses from the forward geocoding, reverse geocoding, and autocomplete operations (including their batch variants). The only value is `FeatureCollection`, as defined in [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946). `Get Polygon` is the one exception: its response root is a `GeoJSON Feature`, see `FeatureTypeEnum`.
  - `features` AutocompleteFeature[] — The array of `GeoJSON Feature` objects returned by the query. Each `Feature` represents a single autocomplete suggestion: its classification (`type`, `typeGroup`), parsed address, and optional place name are exposed via `properties`, and its primary coordinate via `geometry`.
    - `type` 'Feature', required — The `GeoJSON` object type for `Feature` objects. Tags each entry inside the `features` array of a `FeatureCollection` response (geocoding, reverse geocoding, autocomplete) and appears at the root of the `Get Polygon` response. The only value is `Feature`, as defined in [RFC 7946](https://www.rfc-editor.org/rfc/rfc7946).
    - `geometry` GeoJsonPoint — A valid `GeoJSON` geometry object. The type must be one of the seven valid GeoJSON geometry types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon and GeometryCollection. Please refer to [RFC 7946](https://tools.ietf.org/html/rfc7946#section-3.1) for details.
      - `type` 'Point' | 'MultiPoint' | 'LineString' | 'MultiLineString' | 'Polygon' | 'MultiPolygon' | 'GeometryCollection' | 'Feature' | 'FeatureCollection', required — Specifies the `GeoJSON` type. Must be one of the nine valid GeoJSON object types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon, GeometryCollection, Feature and FeatureCollection.
      - `bbox` number[] — Bounding box. Projection used - EPSG:3857. Please refer to [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946#section-5) for details.
    - `properties` AutocompleteProperties, required — The `properties` payload of an `AutocompleteFeature`. Carries the result's classification (`typeGroup`, `type`), its parsed address, and (for many `Place`-typed results) a separate display name.
      - `typeGroup` 'Address' | 'Place' — A coarse classification of an autocomplete suggestion into one of two groups. Used by `Get Autocomplete` both as an input filter via the `resultTypeGroups` query parameter (restricting which kinds of suggestions are returned) and as an output classifier via the `typeGroup` field on each `AutocompleteProperties` (identifying which group a returned suggestion belongs to). The `Address` group covers individual addresses and street segments; the `Place` group covers all other entity types (administrative regions, populated places, natural features, and points of interest).
      - `type` 'Address' | 'AdminDivision1' | 'AdminDivision2' | 'AdminDivision3' | 'AdministrativeBuilding' | 'Airport' | 'AirportTerminal' | 'AmusementPark' | 'AncientSite' | 'Aquarium' | 'Archipelago' | 'Basin' | 'Battlefield' | 'Bay' | 'Beach' | 'Bridge' | 'BusinessStructure' | 'Camp' | 'Canal' | 'Casino' | 'Castle' | 'Cave' | 'Cemetery' | 'Channel' | 'Church' | 'Cliff' | 'Coast' | 'CommunityCenter' | 'Continent' | 'CountryRegion' | 'Crater' | 'CulturalRegion' | 'Dam' | 'Delta' | 'Desert' | 'DrainageBasin' | 'Dune' | 'FacilityStructure' | 'FerryTerminal' | 'FinancialStructure' | 'FireStation' | 'Forest' | 'Fort' | 'Garden' | 'Geyser' | 'Glacier' | 'GolfCourse' | 'GreaterPopulatedPlace' | 'HigherEducationFacility' | 'HistoricalSite' | 'Hospital' | 'HotSpring' | 'Ice' | 'IndigenousPeoplesReserve' | 'IndustrialStructure' | 'Island' | 'Isthmus' | 'Lake' | 'LandArea' | 'Landform' | 'LandmarkBuilding' | 'Library' | 'Lighthouse' | 'Marina' | 'Market' | 'MedicalStructure' | 'MetroStation' | 'MilitaryBase' | 'Mission' | 'Monument' | 'Mosque' | 'Mountain' | 'MountainRange' | 'MultiModalStation' | 'Museum' | 'NauticalStructure' | 'Neighborhood' | 'Oasis' | 'ObservationPoint' | 'Ocean' | 'OfficeBuilding' | 'Other' | 'Park' | 'ParkingStructure' | 'Pass' | 'Peninsula' | 'Plain' | 'Planet' | 'Plateau' | 'Playground' | 'PlayingField' | 'Pole' | 'PoliticalUnit' | 'PopulatedPlace' | 'Port' | 'Postcode1' | 'Promontory' | 'RaceTrack' | 'RailwayStation' | 'Reef' | 'ReligiousStructure' | 'Reserve' | 'ResidentialStructure' | 'River' | 'RoadBlock' | 'Ruin' | 'ScientificResearchBase' | 'Sea' | 'SeaplaneLandingArea' | 'Shrine' | 'SkiArea' | 'Spring' | 'Stadium' | 'StatisticalDistrict' | 'Temple' | 'Theater' | 'TouristRailway' | 'TouristStructure' | 'Trailhead' | 'TransportationStructure' | 'Tunnel' | 'Valley' | 'Volcano' | 'Walkway' | 'Wall' | 'Waterfall' | 'WaterFeature' | 'Wetland' | 'Winery' | 'Zoo' — A classification of autocomplete suggestions used by `Get Autocomplete` both as an input filter (via the `resultTypes` query parameter) and as an output label (via the `type` field on each `AutocompleteProperties`). The members define a gazetteer-style taxonomy spanning addresses, road segments, administrative regions, populated places, natural features, and points of interest. This taxonomy is partitioned into two broader groups by `AutocompleteResultTypeGroupsEnum`: `Address`, which covers addresses and road segments; and `Place`, which covers all other result types.
      - `address` Address — The address of a geocoded or autocomplete-suggested location, parsed into structured fields. Sparseness is normal: only the fields that the resolved entity supplies are populated. For example, `streetName` and `streetNumber` appear only for street-level addresses, and `intersection` appears only for road-intersection results.
        - `addressLine` string — The first line of the address, typically the street name and number. For example, `"15127 NE 24th St"`.
        - `locality` string — The locality the address falls within: usually a city, town, or village. For example: `"Redmond"`.
        - `neighborhood` string — The named neighborhood within the locality, when one is identified.
        - `adminDistricts` AddressAdminDistrictsItem[] — The administrative subdivisions that contain the address, ordered from coarsest to finest. The first entry is typically the first-order subdivision (such as a U.S. state or a Canadian province); subsequent entries cover finer divisions where the country, dependency, or region defines them (such as a county at index 1).
          - `name` string — The full name of the subdivision. For example, `"Washington"` for a U.S. state, or `"King County"` for a county.
          - `shortName` string — The short or abbreviated form of the subdivision name, when one is defined. For example, `"WA"` for a U.S. state. Finer subdivisions often have no distinct short form, in which case `shortName` repeats `name` (such as `"King County"`).
        - `postalCode` string — The postal code for the address, when one is defined. Example: `"98052"`.
        - `countryRegion` AddressCountryRegion — The country or region that contains the address, identified by its display name and ISO 3166-1 Alpha-2 country code. Either field may be omitted in a given response.
          - `ISO` string — The ISO 3166-1 Alpha-2 country code for the country or region. For example, `"US"` for the United States, or `"GB"` for the United Kingdom.
          - `name` string — The display name of the country or region. For example, `"United States"`.
        - `formattedAddress` string — The full address rendered as a single human-readable string, with the components joined according to the conventions of the address's country or region. Example: `"15127 NE 24th St, Redmond, WA 98052"`.
        - `streetName` string — The street name component of the address, when the resolved entity is a street-level address. Example: `"NE 24th St"`.
        - `streetNumber` string — The house or building number on the street, when the resolved entity is a street-level address. Example: `"15127"`.
        - `intersection` Intersection — Intersection details for an address resolved as a road intersection — the corner where two or more named streets meet. Populated only when the resolved entity is a `RoadIntersection`; the parent `Address.intersection` is otherwise omitted.
          - `baseStreet` string — The primary street of the intersection — typically the street the address number references.
          - `secondaryStreet1` string — The first cross street that meets `baseStreet` at the intersection.
          - `secondaryStreet2` string — The second cross street at the intersection, when one is present. Populated only for intersections of three or more streets.
          - `intersectionType` string — A short label describing the form of the intersection. For example, distinguishing an at-grade crossroads from a grade-separated crossing such as a bridge or overpass.
          - `displayName` string — A human-readable name for the intersection that combines the cross streets, such as `"5th Avenue & Main Street"`.
      - `name` string — The display name of the suggested place. Populated for `Place`-typed results when the name is not already represented in the structured `address` (for example, parks, landmarks, or other named features). Omitted for `Address`-typed results and for `Place`-typed results whose name is already included in `address` (such as a populated place whose name appears in `address.locality`).
  - `nextLink` string — Contains the URL to fetch the next page of results if the response is paginated. This is useful when the response is too large to be returned in a single call, allowing users to navigate through multiple pages of results.

## Other responses

- `default` — An unexpected error response.

## Changes

- **2026-07-13** (1.0) `adc95bd8c78a` — 1 warning, 1 info
  - the optional response header `x-ms-request-id` removed for the status `200`
  - added the new optional `header` request parameter `x-ms-client-id`
- **2026-07-13** (1.0) `4464595409b4` — 1 info
  - endpoint added
- **2025-10-15** (1.0) `69718fe8c37a` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/azure/apis/maps-search/changes/geocode:autocomplete/get.md)

---

[API](https://skmtc.dev/azure/apis/maps-search.md) · [All operations](https://skmtc.dev/azure/apis/maps-search/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/azure/maps-search/revisions/adc95bd8c78a/schema)