Search - Get Polygon
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.
GET {endpoint}/search/polygon?api-version=2026-01-01&coordinates={coordinates}
GET {endpoint}/search/polygon?api-version=2026-01-01&coordinates={coordinates}&view={view}&resultType={resultType}&resolution={resolution}
URI Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
|
endpoint
|
path | True |
string (uri) |
The Azure Maps service hostname. Use |
|
api-version
|
query | True |
string minLength: 1 |
The API version to use for this operation. |
|
coordinates
|
query | True |
number[] |
A point on the earth specified as a longitude and latitude. Example: &coordinates=lon,lat |
|
resolution
|
query |
Resolution determines the amount of points to send back. If not specified, the default is medium resolution. |
||
|
result
|
query |
The geopolitical concept to return a boundary for. If not specified, the default is |
||
|
view
|
query |
string |
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. |
Request Header
| Name | Required | Type | Description |
|---|---|---|---|
| x-ms-client-id |
string |
Specifies which account is intended for usage in conjunction with the Azure AD security model. It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management plane Account API. For more information on using Microsoft Entra ID security in Azure Maps, see Manage authentication in Azure Maps. |
|
| Accept-Language |
string |
Language in which search results should be returned. Please refer to Supported Languages for details. |
Responses
| Name | Type | Description |
|---|---|---|
| 200 OK |
The request has succeeded. Media Types: "application/geo+json", "application/json" |
|
| Other Status Codes |
An unexpected error response. Media Types: "application/geo+json", "application/json" Headers x-ms-error-code: string |
Security
AadToken
These are the Microsoft Entra OAuth 2.0 Flows. When paired with Azure role-based access control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.
To implement scenarios, we recommend viewing authentication concepts. In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.
Note
- This security definition requires the use of the
x-ms-client-idheader to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the Maps management API. - The
Authorization URLis specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Microsoft Entra ID configurations. - The Azure role-based access control is configured from the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.
- Usage of the Azure Maps Web SDK allows for configuration based setup of an application for multiple use cases.
- For more information on Microsoft identity platform, see Microsoft identity platform overview.
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/authorize
Scopes
| Name | Description |
|---|---|
| https://atlas.microsoft.com/.default |
subscription-key
This is a shared key that is provisioned when you Create an Azure Maps account in the Azure portal or using PowerShell, CLI, Azure SDKs, or REST API.
With this key, any application can access all REST API. In other words, this key can be used as a master key in the account that they are issued in.
For publicly exposed applications, our recommendation is to use the confidential client applications approach to access Azure Maps REST APIs so your key can be securely stored.
Type:
apiKey
In:
header
SAS Token
This is a shared access signature token is created from the List SAS operation on the Azure Maps resource through the Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.
With this token, any application is authorized to access with Azure role-based access controls and fine-grain control to the expiration, rate, and region(s) of use for the particular token. In other words, the SAS Token can be used to allow applications to control access in a more secured way than the shared key.
For publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the Map account resource to limit rendering abuse and regularly renew the SAS Token.
Type:
apiKey
In:
header
Examples
Get polygon for a city at coordinates -122.204141,47.612560
Sample request
GET https://atlas.microsoft.com/search/polygon?api-version=2026-01-01&coordinates=-122.204141,47.61256&resultType=locality&resolution=small
Sample response
Content-Type: application/geo+json
{
"type": "Feature",
"geometry": {
"type": "GeometryCollection",
"geometries": [
{
"type": "Polygon",
"coordinates": [
[
[
-122.13035,
47.53502
],
[
-122.12882,
47.53567
],
[
-122.12638000000001,
47.535140000000006
],
[
-122.12378000000001,
47.53717
],
[
-122.12068000000001,
47.537620000000004
],
[
-122.12028000000001,
47.538000000000004
],
[
-122.11682,
47.537940000000006
],
[
-122.11527000000001,
47.53609
],
[
-122.11119000000001,
47.536080000000005
],
[
-122.11103000000001,
47.539280000000005
],
[
-122.10832,
47.539530000000006
],
[
-122.10830000000001,
47.54057
],
[
-122.11006,
47.54055
],
[
-122.10999000000001,
47.542640000000006
],
[
-122.11185,
47.54298000000001
],
[
-122.11183000000001,
47.54426
],
[
-122.1114,
47.543800000000005
],
[
-122.10936000000001,
47.54379
],
[
-122.10912,
47.54462
],
[
-122.10745000000001,
47.544830000000005
],
[
-122.10808000000002,
47.545190000000005
],
[
-122.10808000000002,
47.54656000000001
],
[
-122.10665000000002,
47.546580000000006
],
[
-122.10711,
47.544700000000006
],
[
-122.10530000000001,
47.54473
],
[
-122.1054,
47.546910000000004
],
[
-122.10434000000001,
47.54693
],
[
-122.10433,
47.544830000000005
],
[
-122.10056000000002,
47.544940000000004
],
[
-122.1007,
47.548500000000004
],
[
-122.10194000000001,
47.54849
],
[
-122.10194000000001,
47.54883
],
[
-122.10194000000001,
47.549510000000005
],
[
-122.10071,
47.54883
],
[
-122.10048,
47.54849
],
[
-122.10047000000002,
47.54883
],
[
-122.10038000000002,
47.55904
],
[
-122.09796000000001,
47.55923000000001
],
[
-122.09870000000001,
47.560570000000006
],
[
-122.09818000000001,
47.56248
],
[
-122.10011000000002,
47.56839
],
[
-122.09876000000001,
47.56884
],
[
-122.09942000000001,
47.569900000000004
],
[
-122.09782000000001,
47.56983
],
[
-122.09672,
47.58019
],
[
-122.09885000000001,
47.58666
],
[
-122.09796000000001,
47.59503
],
[
-122.09664000000001,
47.602230000000006
],
[
-122.09411000000001,
47.607240000000004
],
[
-122.09104,
47.610240000000005
],
[
-122.08366000000001,
47.615660000000005
],
[
-122.08008000000001,
47.61939
],
[
-122.07904,
47.62201
],
[
-122.07959000000001,
47.627520000000004
],
[
-122.08008000000001,
47.627520000000004
],
[
-122.09181000000001,
47.627520000000004
],
[
-122.09221000000001,
47.62717000000001
],
[
-122.09256,
47.627520000000004
],
[
-122.11094000000001,
47.62765
],
[
-122.11091,
47.636720000000004
],
[
-122.11091,
47.64609
],
[
-122.11431,
47.646060000000006
],
[
-122.11437000000001,
47.64533
],
[
-122.11597,
47.64374
],
[
-122.12254000000001,
47.638510000000004
],
[
-122.12542,
47.636720000000004
],
[
-122.12809000000001,
47.635200000000005
],
[
-122.13241000000001,
47.63515
],
[
-122.13234000000001,
47.63268
],
[
-122.13407000000001,
47.63156000000001
],
[
-122.13484000000001,
47.62935
],
[
-122.13626000000001,
47.62820000000001
],
[
-122.1372,
47.627860000000005
],
[
-122.14184000000002,
47.62787
],
[
-122.14321000000001,
47.62713
],
[
-122.14312000000001,
47.636720000000004
],
[
-122.14335000000001,
47.660590000000006
],
[
-122.1641,
47.66077000000001
],
[
-122.16453000000001,
47.646370000000005
],
[
-122.16797000000001,
47.64621
],
[
-122.19629,
47.64643
],
[
-122.19629,
47.64289
],
[
-122.19846000000001,
47.642860000000006
],
[
-122.19846000000001,
47.64242
],
[
-122.19982000000002,
47.6424
],
[
-122.20169000000001,
47.644600000000004
],
[
-122.20341,
47.643190000000004
],
[
-122.20818000000001,
47.6435
],
[
-122.21014000000001,
47.643130000000006
],
[
-122.20962000000002,
47.642920000000004
],
[
-122.20974000000001,
47.636720000000004
],
[
-122.21005000000001,
47.62107
],
[
-122.22268000000001,
47.62106000000001
],
[
-122.22268000000001,
47.62066
],
[
-122.22203,
47.620470000000005
],
[
-122.22282000000001,
47.619890000000005
],
[
-122.22142000000001,
47.618570000000005
],
[
-122.22248,
47.61838
],
[
-122.22271,
47.617200000000004
],
[
-122.22136,
47.617180000000005
],
[
-122.21985000000001,
47.61643
],
[
-122.22044000000001,
47.614470000000004
],
[
-122.22033,
47.603840000000005
],
[
-122.22043000000001,
47.59682
],
[
-122.21702,
47.59038
],
[
-122.21653,
47.59042
],
[
-122.21572,
47.588240000000006
],
[
-122.21067000000001,
47.58375
],
[
-122.20153,
47.57887
],
[
-122.20227000000001,
47.57864000000001
],
[
-122.20132000000001,
47.578770000000006
],
[
-122.20034000000001,
47.57822
],
[
-122.19901000000002,
47.57592
],
[
-122.19923000000001,
47.567460000000004
],
[
-122.20034000000001,
47.55962
],
[
-122.20072,
47.55966
],
[
-122.20114000000001,
47.557520000000004
],
[
-122.20119000000001,
47.54943
],
[
-122.20160000000001,
47.549440000000004
],
[
-122.20167000000001,
47.54883
],
[
-122.20200000000001,
47.54609000000001
],
[
-122.19676000000001,
47.54621
],
[
-122.19545000000001,
47.54609000000001
],
[
-122.19545000000001,
47.545750000000005
],
[
-122.19091000000002,
47.54580000000001
],
[
-122.1907,
47.54216
],
[
-122.18581,
47.542100000000005
],
[
-122.18116,
47.541140000000006
],
[
-122.17142000000001,
47.54086
],
[
-122.16987,
47.54008
],
[
-122.16797000000001,
47.540060000000004
],
[
-122.16554000000001,
47.54005
],
[
-122.16439000000001,
47.54281
],
[
-122.16433,
47.545480000000005
],
[
-122.15356000000001,
47.54538
],
[
-122.15359000000001,
47.541760000000004
],
[
-122.14280000000001,
47.541520000000006
],
[
-122.14288,
47.539370000000005
],
[
-122.13645000000001,
47.53826
],
[
-122.13035,
47.53502
]
],
[
[
-122.19957000000001,
47.58372000000001
],
[
-122.20448,
47.583830000000006
],
[
-122.20585000000001,
47.586780000000005
],
[
-122.19654000000001,
47.586740000000006
],
[
-122.19655000000002,
47.58379
],
[
-122.19957000000001,
47.58372000000001
]
]
]
}
]
},
"properties": {
"name": "Bellevue",
"copyright": "© 2022 Microsoft and its suppliers. This API and any results cannot be used or accessed without Microsoft's express written permission.",
"copyrightUrl": "https://azure.microsoft.com/en-us/support/legal/preview-supplemental-terms/",
"geometriesCopyright": [
{
"sourceName": "TOM",
"copyright": "TomTom"
}
]
}
}
Definitions
| Name | Description |
|---|---|
|
Azure. |
The error object. |
|
Azure. |
A response containing error details. |
|
Azure. |
An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors. |
| Boundary |
The successful response body returned by |
|
Boundary |
The |
|
Boundary |
The geographic hierarchy level requested when calling |
|
Feature |
The |
|
Geo |
A valid |
|
Geo |
A valid |
|
Geo |
A valid |
|
Geo |
A valid |
|
Geo |
A valid |
|
Geo |
Specifies the |
|
Geo |
A valid |
|
Geo |
A valid |
|
Geometry |
A single per-geometry data-provider attribution entry within
|
|
Resolution |
The level of detail used for the |
Azure.Core.Foundations.Error
The error object.
| Name | Type | Description |
|---|---|---|
| code |
string |
One of a server-defined set of error codes. |
| details |
An array of details about specific errors that led to this reported error. |
|
| innererror |
An object containing more specific information than the current object about the error. |
|
| message |
string |
A human-readable representation of the error. |
| target |
string |
The target of the error. |
Azure.Core.Foundations.ErrorResponse
A response containing error details.
| Name | Type | Description |
|---|---|---|
| error |
The error object. |
Azure.Core.Foundations.InnerError
An object containing more specific information about the error. As per Azure REST API guidelines - https://aka.ms/AzureRestApiGuidelines#handling-errors.
| Name | Type | Description |
|---|---|---|
| code |
string |
One of a server-defined set of error codes. |
| innererror |
Inner error. |
Boundary
The successful response body returned by Get Polygon. Encoded as a
GeoJSON Feature whose geometry is
a GeometryCollection of one or more Polygon or MultiPolygon shapes describing the
outline of the requested geographical area, and whose properties carry the area's
display name and copyright attribution.
| Name | Type | Description |
|---|---|---|
| geometry |
A |
|
| properties |
Display name and copyright attribution for the returned area. See |
|
| type |
The |
BoundaryProperties
The properties payload of a Boundary. Carries the display name of the returned
geographical area along with copyright attribution, both an API-wide notice and
per-geometry data-provider credits.
| Name | Type | Description |
|---|---|---|
| copyright |
string |
The Azure Maps API copyright and usage notice that applies to this response. Distinct
from the per-geometry data-provider attributions in |
| copyrightUrl |
string |
A URL to Azure Maps copyright and licensing information for the API and its underlying data sources. |
| geometriesCopyright |
Per-geometry data-provider attribution. Each entry corresponds positionally to the
matching shape in the parent |
|
| name |
string |
The display name of the geographical area, for example, |
BoundaryResultTypeEnum
The geographic hierarchy level requested when calling Get Polygon. The value is supplied
as the resultType query parameter and selects which level of the administrative or postal
hierarchy the returned Boundary polygon outlines. Defaults to countryRegion when not
specified.
| Value | Description |
|---|---|
| countryRegion |
A country or region. |
| adminDistrict |
First administrative level within the country/region, such as a state or a province. |
| adminDistrict2 |
Second administrative level within the country/region, such as a county. |
| postalCode |
The smallest postal code category, such as a zip code. |
| postalCode2 |
The next largest postal code category after |
| postalCode3 |
The next largest postal code category after |
| postalCode4 |
The next largest postal code category after |
| neighborhood |
A locally recognized area within a populated place, often with informal or culturally defined boundaries. |
| locality |
A concentrated area of human settlement, such as a city, town or village. |
FeatureTypeEnum
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.
| Value | Description |
|---|---|
| Feature |
The |
GeoJsonGeometryCollection
A valid GeoJSON GeometryCollection object type. Please refer to RFC
7946 for details.
| Name | Type | Description |
|---|---|---|
| bbox |
number[] (double) |
Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details. |
| geometries | GeoJsonGeometry[]: |
Contains a list of valid |
| type |
string:
Geometry |
Specifies the |
GeoJsonLineString
A valid GeoJSON LineString geometry type. Please refer to RFC
7946 for details.
| Name | Type | Description |
|---|---|---|
| bbox |
number[] (double) |
Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details. |
| coordinates |
number[] (double) |
Coordinates for the |
| type |
string:
Line |
Specifies the |
GeoJsonMultiLineString
A valid GeoJSON MultiLineString geometry type. Please refer to RFC
7946 for details.
| Name | Type | Description |
|---|---|---|
| bbox |
number[] (double) |
Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details. |
| coordinates |
number[] (double) |
Coordinates for the |
| type |
string:
Multi |
Specifies the |
GeoJsonMultiPoint
A valid GeoJSON MultiPoint geometry type. Please refer to RFC
7946 for details.
| Name | Type | Description |
|---|---|---|
| bbox |
number[] (double) |
Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details. |
| coordinates |
number[] (double) |
Coordinates for the |
| type |
string:
Multi |
Specifies the |
GeoJsonMultiPolygon
A valid GeoJSON MultiPolygon object type. Please refer to RFC
7946 for details.
| Name | Type | Description |
|---|---|---|
| bbox |
number[] (double) |
Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details. |
| coordinates |
number[] (double) |
Contains a list of valid |
| type |
string:
Multi |
Specifies the |
GeoJsonObjectType
Specifies the GeoJSON type. Must be one of the nine valid GeoJSON object
types - Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon,
GeometryCollection, Feature and FeatureCollection.
| Value | Description |
|---|---|
| Point |
|
| MultiPoint |
|
| LineString |
|
| MultiLineString |
|
| Polygon |
|
| MultiPolygon |
|
| GeometryCollection |
|
| Feature |
|
| FeatureCollection |
|
GeoJsonPoint
A valid GeoJSON Point geometry type. Please refer to RFC
7946 for details.
| Name | Type | Description |
|---|---|---|
| bbox |
number[] (double) |
Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details. |
| coordinates |
number[] (double) |
A |
| type |
string:
Point |
Specifies the |
GeoJsonPolygon
A valid GeoJSON Polygon geometry type. Please refer to RFC
7946 for details.
| Name | Type | Description |
|---|---|---|
| bbox |
number[] (double) |
Bounding box. Projection used - EPSG:3857. Please refer to RFC 7946 for details. |
| coordinates |
number[] (double) |
Coordinates for the |
| type |
string:
Polygon |
Specifies the |
GeometryCopyright
A single per-geometry data-provider attribution entry within
BoundaryProperties.geometriesCopyright. Identifies the source of one geometry in
the parent Boundary.geometry.geometries array.
| Name | Type | Description |
|---|---|---|
| copyright |
string |
The human-readable attribution string for the data provider. For example, |
| sourceName |
string |
An identifier for the data provider that supplied this geometry. |
ResolutionEnum
The level of detail used for the Boundary polygon returned by Get Polygon. Supplied as
the resolution query parameter, the value selects how many points outline the boundary,
in ascending order: small, medium, large, huge. Higher levels use the same number
of points as the next lower level or more. Defaults to medium when not specified.
| Value | Description |
|---|---|
| small |
Returns the boundary geometry with the fewest points. |
| medium |
Returns the boundary geometry with the same number of points as |
| large |
Returns the boundary geometry with the same number of points as |
| huge |
Returns the boundary geometry with the same number of points as |