你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Search - Get Geocode Autocomplete

服务:: Maps

API 版本:: 2025-06-01-preview

用于根据用户的位置和部分查询获取建议实体的排名列表。

给定具有用户位置的请求和用作完整查询字符串前缀（称为查询前缀）的部分查询，Azure Maps 自动完成 API 将返回用户最有可能搜索的建议实体列表。这些实体从最有可能到最不可能进行排名。

重要

通过使用此功能，你同意预览版法律条款。有关详细信息，请参阅预览版补充条款。

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query={query}

具有可选参数:

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query={query}&coordinates={coordinates}&bbox={bbox}&top={top}&resultTypeGroups={resultTypeGroups}&resultTypes={resultTypes}&view={view}&countryRegion={countryRegion}

URI 参数

名称	在	必需	类型	说明
api-version	query	True	string	Azure Maps API 的版本号。
query	query	True	string	必填。用户的查询前缀。示例：“1 Micro”或“Muir Woods”。
bbox	query		number[]	未提供时 `coordinates` 必需。地球上的矩形区域定义为边界框对象。矩形的边由经度和纬度值定义。指定此参数时，在计算位置查询结果时将考虑地理区域。示例：lon1，lat1，lon2，lat2。最小尺寸：约 0.00001 度（~0.01 米）。最大大小：最大到全局范围（-180，-90 到 180,90）
coordinates	query		number[]	未提供时 `bbox` 必需。地球上指定为经度和纬度的点。指定此参数时，将考虑用户的位置，并且返回的结果可能与用户更相关。示例：&coordinates=lon，lat 注意：`coordinates` 如果提供了，则 `bbox` 成为辅助信号。
countryRegion	query		string	自动完成结果的信号为指定的 ISO 3166-1 Alpha-2 地区/国家/地区代码，例如 FR。仅返回指定国家/地区的结果。
resultTypeGroups	query		AutocompleteResultTypeGroupsEnum[]	返回的实体类型组的逗号分隔列表。可能的值是地址地方
resultTypes	query		AutocompleteResultTypeEnum[]	返回的实体类型的逗号分隔列表。当类型组设置为地址时，支持的类型包括：地址路障所有其他类型都属于“地点”类型组。这些可能包括 AdminDivision1、Neighborhood、PopulatedPlace 等实体。默认值是所有可能的实体类型。
top	query		integer (int32) minimum: 1 maximum: 20	将返回的最大响应数。默认值：5，最小值：1，最大值：20。
view	query		string	表示 ISO 3166-1 Alpha-2 区域/国家/地区代码的字符串。这将更改地缘政治争议边界和标签，以与指定的用户区域保持一致。默认情况下，“视图”参数设置为“自动”，即使您尚未在请求中定义它也是如此。有关详细信息，请参阅支持的视图，并查看可用的视图。

请求头

名称	必需	类型	说明
x-ms-client-id		string	指定哪个帐户旨在与 Azure AD 安全模型结合使用。它表示 Azure Maps 帐户的唯一 ID，可以从 Azure Maps 管理平面帐户 API 检索。有关在 Azure Maps 中使用 Microsoft Entra ID 安全性的详细信息，请参阅在 Azure Maps 中管理身份验证。
Accept-Language		string	应返回搜索结果的语言。有关详细信息，请参阅支持的语言。

名称

必需

类型

说明

x-ms-client-id

string

指定哪个帐户旨在与 Azure AD 安全模型结合使用。它表示 Azure Maps 帐户的唯一 ID，可以从 Azure Maps 管理平面帐户 API 检索。有关在 Azure Maps 中使用 Microsoft Entra ID 安全性的详细信息，请参阅在 Azure Maps 中管理身份验证。

Accept-Language

string

应返回搜索结果的语言。

有关详细信息，请参阅支持的语言。

响应

名称	类型	说明
200 OK	AutocompleteResponse	好的 Media Types: "application/geo+json" 标头 x-ms-request-id: string
Other Status Codes	ErrorResponse	发生意外错误。 Media Types: "application/geo+json"

名称

类型

说明

200 OK

AutocompleteResponse

好的

Media Types: "application/geo+json"

标头

x-ms-request-id: string

Other Status Codes

ErrorResponse

发生意外错误。

Media Types: "application/geo+json"

安全性

AADToken

这些 Microsoft Entra OAuth 2.0 流。与 Azure 基于角色的访问配对时，控制它可用于控制对 Azure Maps REST API 的访问。 Azure 基于角色的访问控制用于指定对一个或多个 Azure Maps 资源帐户或子资源的访问。任何用户、组或服务主体都可以通过内置角色或由一个或多个对 Azure Maps REST API 的权限组成的自定义角色授予访问权限。

若要实现方案，建议查看身份验证概念。总之，此安全定义提供了一种解决方案，用于通过能够针对特定 API 和范围进行访问控制的对象对应用程序建模。

注释

此安全定义要求使用 x-ms-client-id 标头来指示应用程序请求访问的 Azure Maps 资源。这可以从地图管理 API获取。
Authorization URL 特定于 Azure 公有云实例。主权云具有唯一的授权 URL，Microsoft Entra ID 配置。
Azure 基于角色的访问控制是通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 从 Azure 管理平面配置的。
使用 Azure Maps Web SDK 允许为多个用例设置基于应用程序的配置。
有关Microsoft标识平台的详细信息，请参阅 Microsoft标识平台概述。

类型: oauth2
流向: implicit
授权 URL: https://login.microsoftonline.com/common/oauth2/authorize

作用域

名称	说明
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

这是在通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 通过 Azure 管理平面创建 Azure Maps 资源时预配的共享密钥。

使用此密钥，任何应用程序都有权访问所有 REST API。换句话说，这些密钥当前可视为为其颁发的帐户的主密钥。

对于公开的应用程序，我们建议使用可安全地存储此密钥的 Azure Maps REST API 的服务器到服务器访问。

类型: apiKey
在: header

SAS Token

这是一个共享访问签名令牌，它通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 通过 Azure 管理平面在 azure Maps 资源上的列表 SAS 操作创建。

使用此令牌，任何应用程序都有权使用 Azure 基于角色的访问控制进行访问，并精细控制特定令牌的过期、速率和区域。换句话说，SAS 令牌可用于允许应用程序以比共享密钥更安全的方式控制访问。

对于公开的应用程序，建议在映射帐户资源上配置允许的源的特定列表，以限制呈现滥用并定期续订 SAS 令牌。

类型: apiKey
在: header

示例

Autocomplete API call to search for '1 Microsoft'

Autocomplete API call to search for '1 Microsoft Way, Redmond', filtered by roadblock resultTypes, place resultTypeGroups, and return empty result

Autocomplete API call to search for 'Muir Woods', filtered by address resultTypeGroups

Autocomplete API call to search for 'Muir Woods', filtered by park and populated place resultTypes, place resultTypeGroups

Autocomplete API call to search for 'Muir Woods', filtered by park resultTypes

Autocomplete API call to search for 'Muir Woods', filtered by place resultTypeGroups

Autocomplete API call to search for 'Muir Woods', filtered by roadblock resultTypes, address resultTypeGroups

Autocomplete API call to search for '1 Microsoft'

示例请求

HTTP

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=1 Microsoft&coordinates=-113.301894,49.201888

示例响应

状态代码:: 200

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Address",
        "type": "Address",
        "address": {
          "streetNumber": "1",
          "streetName": "Microsoft Way",
          "addressLine": "1 Microsoft Way",
          "locality": "Redmond",
          "adminDistricts": [
            {
              "name": "Washington"
            },
            {
              "name": "King County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "postalCode": "98052",
          "formattedAddress": "1 Microsoft Way, Redmond, Washington 98052, United States"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "LandmarkBuilding",
        "address": {
          "locality": "Bellevue",
          "adminDistricts": [
            {
              "name": "Washington"
            },
            {
              "name": "King County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "formattedAddress": "Bellevue, Washington, United States"
        },
        "name": "Microsoft-Advanta C"
      }
    }
  ]
}

Autocomplete API call to search for '1 Microsoft Way, Redmond', filtered by roadblock resultTypes, place resultTypeGroups, and return empty result

示例请求

HTTP

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=1 Microsoft Way, Redmond&coordinates=-113.301894,49.201888&resultTypeGroups=Place&resultTypes=RoadBlock

示例响应

状态代码:: 200

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": []
}

Autocomplete API call to search for 'Muir Woods', filtered by address resultTypeGroups

示例请求

HTTP

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-113.301894,49.201888&resultTypeGroups=Address

示例响应

状态代码:: 200

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Address",
        "type": "Address",
        "address": {
          "streetName": "Muir Woods Rd",
          "addressLine": " Muir Woods Rd",
          "locality": "Sausalito",
          "adminDistricts": [
            {
              "name": "California"
            },
            {
              "name": "Marin County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "postalCode": "94965",
          "formattedAddress": "Muir Woods Rd, Sausalito, California 94965, United States"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Address",
        "type": "RoadBlock",
        "address": {
          "streetName": "Muir St",
          "addressLine": " Muir St",
          "locality": "Grosse Pointe Farms",
          "adminDistricts": [
            {
              "name": "Michigan"
            },
            {
              "name": "Wayne County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "postalCode": "48236",
          "formattedAddress": "Muir St, Grosse Pointe Farms, Michigan 48236, United States"
        }
      }
    }
  ]
}

Autocomplete API call to search for 'Muir Woods', filtered by park and populated place resultTypes, place resultTypeGroups

示例请求

HTTP

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-122.581711,37.896980&resultTypeGroups=Place&resultTypes=Park,PopulatedPlace

示例响应

状态代码:: 200

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "PopulatedPlace",
        "address": {
          "locality": "Muir Woods",
          "adminDistricts": [
            {
              "name": "Georgia"
            },
            {
              "name": "Fulton County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "postalCode": "30349",
          "formattedAddress": "Muir Woods, Georgia 30349, United States"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "Park",
        "address": {
          "adminDistricts": [
            {
              "name": "California"
            },
            {
              "name": "Marin County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "formattedAddress": "California"
        },
        "name": "Muir Woods National Park"
      }
    }
  ]
}

Autocomplete API call to search for 'Muir Woods', filtered by park resultTypes

示例请求

HTTP

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-122.581711,37.896980&resultTypes=Park

示例响应

状态代码:: 200

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "Park",
        "address": {
          "adminDistricts": [
            {
              "name": "California"
            },
            {
              "name": "Marin County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "formattedAddress": "California"
        },
        "name": "Muir Woods National Monument"
      }
    }
  ]
}

Autocomplete API call to search for 'Muir Woods', filtered by place resultTypeGroups

示例请求

HTTP

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-122.581711,37.896980&resultTypeGroups=Place

示例响应

状态代码:: 200

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "Forest",
        "address": {
          "adminDistricts": [
            {
              "name": "Wisconsin"
            },
            {
              "name": "Dane County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "formattedAddress": "Wisconsin"
        },
        "name": "Muir Woods"
      }
    },
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "PopulatedPlace",
        "address": {
          "locality": "Muir Woods",
          "adminDistricts": [
            {
              "name": "Georgia"
            },
            {
              "name": "Fulton County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "postalCode": "30349",
          "formattedAddress": "Muir Woods, Georgia 30349, United States"
        }
      }
    },
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Place",
        "type": "Park",
        "address": {
          "adminDistricts": [
            {
              "name": "California"
            },
            {
              "name": "Marin County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "formattedAddress": "California"
        },
        "name": "Muir Woods National Monument"
      }
    }
  ]
}

Autocomplete API call to search for 'Muir Woods', filtered by roadblock resultTypes, address resultTypeGroups

示例请求

HTTP

GET https://atlas.microsoft.com/geocode:autocomplete?api-version=2025-06-01-preview&query=Muir Woods&coordinates=-113.301894,49.201888&resultTypeGroups=Address&resultTypes=RoadBlock

示例响应

状态代码:: 200

Content-Type: application/geo+json

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": null,
      "properties": {
        "typeGroup": "Address",
        "type": "RoadBlock",
        "address": {
          "streetName": "Muir St",
          "addressLine": " Muir St",
          "locality": "Grosse Pointe Farms",
          "adminDistricts": [
            {
              "name": "Michigan"
            },
            {
              "name": "Wayne County"
            }
          ],
          "countryRegion": {
            "ISO": "US",
            "name": "United States"
          },
          "postalCode": "48236",
          "formattedAddress": "Muir St, Grosse Pointe Farms, Michigan 48236, United States"
        }
      }
    }
  ]
}

定义

名称	说明
Address	结果的地址
AdminDistricts	地址所在国家或地区的细分名称。此元素通常被视为第一个顺序管理细分，但在某些情况下，它还包含国家/地区、依赖项或区域的第二、第三或第四个顺序细分。
AutocompleteFeature	自动完成结果的特点
AutocompleteProperties	自动完成结果的属性
AutocompleteResponse	此对象是从成功的自动完成调用中返回的。
AutocompleteResultTypeEnum	建议类型
AutocompleteResultTypeGroupsEnum	地址或地点
CountryRegion	国家或地区及其名称和 ISO 代码。
ErrorAdditionalInfo	资源管理错误附加信息。
ErrorDetail	错误详细信息。
ErrorResponse	错误响应
FeatureCollectionEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 `FeatureCollection`。有关详细信息，请参阅 RFC 7946。
FeatureTypeEnum	特征的类型必须是特征。
GeoJsonPoint	有效的 `GeoJSON Point` 几何图形类型。有关详细信息，请参阅 RFC 7946。
Intersection	结果的地址。

Address

Object

结果的地址

名称	类型	说明
addressLine	string	包含街道名称和街道号码的地址行
adminDistricts	AdminDistricts[]	地址所在国家或地区的细分名称。此元素通常被视为第一个顺序管理细分，但在某些情况下，它还包含国家/地区、依赖项或区域的第二、第三或第四个顺序细分。
countryRegion	CountryRegion	国家或地区及其名称和 ISO 代码。
formattedAddress	string	格式化地址属性
intersection	Intersection	结果的地址。
locality	string	Locality 属性
neighborhood	string	邻里物业
postalCode	string	邮政编码属性
streetName	string	formattedAddress 中的街道名称
streetNumber	string	街道上的号码（如果可用），来自 formattedAddress

AdminDistricts

Object

地址所在国家或地区的细分名称。此元素通常被视为第一个顺序管理细分，但在某些情况下，它还包含国家/地区、依赖项或区域的第二、第三或第四个顺序细分。

名称	类型	说明
name	string	相应 adminDistrict 字段的名称，对于 adminDistrict[0]，这可以是州的全名，例如 Washington，对于 adminDistrict[1]，这可以是县的全名
shortName	string	相应 adminDistrict 字段的简称，对于 adminDistrict[0]，这可以是州的简称，例如 WA，对于 adminDistrict[1]，这可以是县的简称

AutocompleteFeature

Object

自动完成结果的特点

名称	类型	说明
geometry	GeoJsonPoint	有效的 `GeoJSON Point` 几何图形类型。有关详细信息，请参阅 RFC 7946。
properties	AutocompleteProperties	自动完成结果的属性
type	FeatureTypeEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 Feature。有关详细信息，请参阅 RFC 7946。

AutocompleteProperties

Object

自动完成结果的属性

名称	类型	说明
address	Address	结果的地址
name	string	地点的名称。如果返回的类型为“地址”，则不会显示此字段。
type	AutocompleteResultTypeEnum	建议类型
typeGroup	AutocompleteResultTypeGroupsEnum	地址或地点

AutocompleteResponse

Object

此对象是从成功的自动完成调用中返回的。

名称	类型	说明
features	AutocompleteFeature[]	自动完成结果的特点
nextLink	string	该链接指向返回的功能的下一页。如果是最后一页，则不显示此字段。
type	FeatureCollectionEnum	指定 `GeoJSON` 类型。唯一支持的对象类型是 `FeatureCollection`。有关详细信息，请参阅 RFC 7946。

AutocompleteResultTypeEnum

枚举

建议类型

值	说明
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
WaterFeature
Waterfall
Wetland
Winery
Zoo

AutocompleteResultTypeGroupsEnum

枚举

地址或地点

值	说明
Address	特定地址位置。支持的类型包括：地址路障
Place	所有其他类型都属于“地点”类型组。这些可能包括 AdminDivision1、Neighborhood、PopulatedPlace 等实体。

值

说明

Address

特定地址位置。支持的类型包括：

地址
路障

Place

所有其他类型都属于“地点”类型组。这些可能包括 AdminDivision1、Neighborhood、PopulatedPlace 等实体。

CountryRegion

Object

国家或地区及其名称和 ISO 代码。

名称	类型	说明
ISO	string	国家/地区的ISO
name	string	国家/地区的名称

ErrorAdditionalInfo

Object

资源管理错误附加信息。

名称	类型	说明
info	object	其他信息。
type	string	其他信息类型。

ErrorDetail

Object

错误详细信息。

名称	类型	说明
additionalInfo	ErrorAdditionalInfo[]	错误附加信息。
code	string	错误代码。
details	ErrorDetail[]	错误详细信息。
message	string	错误消息。
target	string	错误目标。

ErrorResponse

Object

错误响应

名称	类型	说明
error	ErrorDetail	错误对象。

FeatureCollectionEnum

枚举

指定 GeoJSON 类型。唯一支持的对象类型是 FeatureCollection。有关详细信息，请参阅 RFC 7946。

值	说明
FeatureCollection	指定 `GeoJSONFeatureCollection` 对象类型。

FeatureTypeEnum

枚举

特征的类型必须是特征。

值	说明
Feature	指定功能对象类型 `GeoJSON`。

GeoJsonPoint

Object

有效的 GeoJSON Point 几何图形类型。有关详细信息，请参阅 RFC 7946。

名称	类型	说明
bbox	number[] (double)	边界框。使用的投影 - EPSG：3857。有关详细信息，请参阅 RFC 7946。
coordinates	number[] (double)	`Position` 是包含两个或多个元素的数字数组。前两个元素经度和纬度，精确按顺序排列。海拔/海拔是可选的第三个元素。有关详细信息，请参阅 RFC 7946。
type	string: Point	指定 `GeoJSON` 类型。必须是九种有效的 GeoJSON 对象类型之一 - Point、MultiPoint、LineString、MultiLineString、Polygon、MultiPolygon、GeometryCollection、Feature 和 FeatureCollection。

Intersection

Object

结果的地址。

名称	类型	说明
baseStreet	string	该位置的主要街道。
displayName	string	交叉点的完整名称。
intersectionType	string	交叉点的类型。
secondaryStreet1	string	第一条相交的街道。
secondaryStreet2	string	如果有，则为第二条相交街道。