---
title: "Use to get longitude and latitude coordinates of a street address or name of a place."
method: GET
path: "/geocode"
---

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

`GET /geocode`

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.

## Query parameters

- `api-version` string, required
- `top` integer
- `query` string
- `addressLine` string
- `countryRegion` string
- `bbox` number[]
- `view` string
- `coordinates` number[]
- `adminDistrict` string
- `adminDistrict2` string
- `adminDistrict3` string
- `locality` string
- `postalCode` string

## Headers

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

## Response `200`

The request has succeeded.

- GeocodingResponse — The successful response body returned by `Get Geocoding` and `Get Reverse Geocoding`, and the per-batch-item success shape carried inside `GeocodingBatchResponse.batchItems`. Encoded as a [`GeoJSON FeatureCollection`](https://www.rfc-editor.org/rfc/rfc7946) whose `features` array contains one `Feature` per geocoded location.
  - `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` FeaturesItem[] — The array of `GeoJSON Feature` objects returned by the query. Each `Feature` represents a single geocoded location: its address components, match-quality indicators, and geocode points are exposed via `properties`, and its primary coordinate via `geometry`.
    - `type` 'Feature' — 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).
    - `id` string — An optional service-assigned identifier for the feature, when one is available.
    - `properties` FeaturesItemProperties — The `properties` payload of a feature in a `GeocodingResponse`. Carries the entity type and match-quality indicators for the geocoded location, its parsed address components, and one or more geocode points that pin the location to specific coordinates.
      - `type` string — The entity type that the geocoded location resolved to. One of: `Address`, `RoadBlock`, `RoadIntersection`, `Neighborhood`, `PopulatedPlace`, `Postcode1`, `AdminDivision1`, `AdminDivision2`, or `CountryRegion`.
      - `confidence` 'High' | 'Medium' | 'Low' — The level of confidence that the geocoded location result is a match. Use this value together with the match codes to obtain more complete information about the match. The confidence of a geocoded location is based on many factors, including the relative importance of the geocoded location and the user's location, if specified.
      - `matchCodes` MatchCodesEnum[] — How the geocoding service produced this result relative to the query: a direct match at the requested specificity (`Good`), one of several candidates (`Ambiguous`), or a fallback to a less precise level of the geographic hierarchy (`UpHierarchy`). Multiple values may be present. For example, an `Ambiguous` plus `UpHierarchy` pairing indicates that the service could not match the requested specificity and found multiple matches at a coarser level. See `MatchCodesEnum` for per-value descriptions; combine with `confidence` for a complete picture of match quality.
      - `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"`.
      - `geocodePoints` GeocodePointsItem[] — One or more geocode points for the location, each marked with how it was derived (`calculationMethod`) and what it is best suited for (`usageTypes`). For example, `Display` for visual placement on a map, or `Route` for use as a navigation destination.
        - `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.
        - `calculationMethod` 'Interpolation' | 'InterpolationOffset' | 'Parcel' | 'Rooftop' — The method that was used to compute the geocode point.
        - `usageTypes` UsageTypeEnum[] — What the geocode point is best suited for — `Display` for visual placement on a map, or `Route` as a routing destination. A point may carry both. See `UsageTypeEnum` for the per-value details, including how each is positioned for features with non-trivial extent.
    - `geometry` GeoJsonPoint, required — 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.
    - `bbox` number[] — The smallest axis-aligned rectangle that contains the feature's geometry, in WGS 84 longitude/latitude order. Encoded as `[westLon, southLat, eastLon, northLat]` per [RFC 7946, Section 5](https://datatracker.ietf.org/doc/html/rfc7946#section-5).
  - `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) `2bfc7c2d192d` — 1 info
  - endpoint added
- **2026-07-13** (1.0) `0e0c2063abbc` — 1 breaking
  - api path removed without deprecation
- **2026-07-13** (1.0) `c6ee214858e9` — 1 info
  - added the new optional `query` request parameter `query`
- **2025-10-15** (1.0) `69718fe8c37a` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/azure/apis/maps-search/changes/geocode/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)