이 문서에서는 Bing Maps Query로 위치 찾기 API를 Azure Maps 지오코딩 가져오기 API로 마이그레이션하는 방법을 설명합니다. Azure Maps 지오코딩 가져오기 API는 거리 주소, 장소 또는 랜드마크의 경도 및 위도 좌표를 가져오는 데 사용됩니다. Azure Maps 지오코딩 가져오기 API는 구조화되지 않은 형식이나 구조화된 형식의 지오코딩 입력을 지원합니다. 이 마이그레이션 설명서는 거리 주소, 지역, 우편 번호 또는 랜드마크 이름과 같은 지오코딩 입력이 Bing Maps Query로 위치 찾기 API가 지원하는 것과 유사한 구조화되지 않은 형식(query=)일 때의 시나리오를 위한 것입니다. 지오코딩 입력이 주소로 위치를 찾도록 구조화된 Bing Maps 시나리오를 마이그레이션하는 방법에 관한 자세한 내용은 Bing Maps 주소로 위치 찾기 API 마이그레이션을 참조하세요.
필수 조건
- Azure 계정
- Azure Maps 계정
- 구독 키 또는 다른 형태의 Azure Maps를 사용한 인증
주요 차이점
- Bing Maps Query로 위치 찾기 API는 구조화되지 않은 형식의 지오코딩 입력만 지원하는 반면, Azure Maps 지오코딩 가져오기 API는 구조화되지 않은(query=) 또는 구조화된(addressLine=) 형식의 지오코딩 입력을 지원합니다. 랜드마크 이름을 지오코딩하려면 구조화되지 않은 입력 형식을 사용하여 Azure Maps 지오코딩 가져오기 API를 사용합니다.
- Bing Maps Query로 위치 찾기 API는 위도/경도 형식으로 좌표를 반환하는 반면, Azure Maps 지오코딩 가져오기 API는 GeoJSON 형식에 정의된 대로 경도/위도 형식으로 좌표를 반환합니다.
- Bing Maps Query로 위치 찾기 API는 XML 및 JSON 응답 형식을 지원합니다. Azure Maps 지오코딩 가져오기 API는 GeoJSON을 지원합니다.
- Bing Maps Query로 위치 찾기 API와 달리 Azure Maps 지오코딩 가져오기 API에는 ISO 3166-1 Alpha-2 지역/국가 번호를 나타내는 문자열인
view입력 매개 변수가 있습니다.view입력 매개 변수는 지정된 사용자 지역에 맞춰 지정학적 분쟁 국경과 레이블을 변경합니다. 자세한 내용은 URI 매개 변수를 참조하세요. - Bing Maps Query로 위치 찾기 API와 달리 Azure Maps 지오코딩 가져오기 API는 현재 중국, 일본 또는 한국에 대한 주소 지오코딩을 지원하지 않습니다.
- 엔터프라이즈용 Bing Maps와 달리 Azure Maps는 지리적 범위 지정을 지원하는 글로벌 서비스로, 데이터 보존을 유럽(EU) 또는 미국(US) 지리적 영역(geos)으로 제한할 수 있습니다. 모든 요청(입력 데이터 포함)은 지정된 지리적 영역에서만 처리됩니다. 자세한 내용은 지리적 범위를 참조하세요.
보안 및 인증
엔터프라이즈용 Bing Maps는 API 키 인증만 지원합니다. Azure Maps는 구독 키, Microsoft Entra ID, SAS(공유 액세스 서명) 토큰 등 API 호출을 인증하는 다양한 방법을 지원합니다. Azure Maps의 보안 및 인증에 대한 자세한 내용은 Azure Maps 지오코딩 가져오기 설명서의 Azure Maps를 사용한 인증 및 보안 섹션을 참조하세요.
요청 매개 변수
다음 표에는 Bing Maps의 Query로 위치 찾기 요청 매개 변수와 이에 상응하는 Azure Maps 매개 변수가 나열되어 있습니다.
| Bing 지도 요청 매개 변수 | Bing 지도 요청 매개 변수 별칭 | Azure Maps 요청 매개 변수 | Azure Maps에 필요 | Azure Maps 데이터 형식 | 설명 |
|---|---|---|---|---|---|
| culture | c | 요청 헤더: Accept-Language | False | string | Azure Maps 요청 헤더에 지정된 대로 culture는 Azure Maps 지오코딩 가져오기 API를 사용할 때 검색 결과에 사용되는 언어를 정의합니다. 자세한 내용은 지원되는 언어를 참조하세요. |
| include | incl | 필요하지 않음 | 필요하지 않음 | 필요하지 않음 | Bing Maps Query로 위치 찾기 API에서 include 입력 매개 변수는 응답의 위치 결과에 2개 문자로 된 ISO 국가 코드를 가져와야 하고(include=ciso2) 응답에서 쿼리 문자열이 주소 값으로 구문 분석되는 방식을 보여주도록 지정해야 합니다(include=queryParse). Azure Maps 지오코딩 가져오기 API에서 2개 문자로 된 ISO 국가 코드는 기본적으로 반환되며 queryParse를 지원하지 않습니다. |
| includeNeighborhood | inclnb | 필요하지 않음 | 필요하지 않음 | 필요하지 않음 | Azure Maps 지오코딩 가져오기 API에서는 사용 가능한 경우 기본적으로 인근 지역 정보가 응답으로 반환됩니다. |
| maxResults | maxRes | top | False | 정수(int32) | Azure Maps 지오코딩 가져오기 API에서 반환되는 기본 응답 수는 5입니다. 최솟값은 1이고 최댓값은 20입니다. |
| query | q | 쿼리 | True | string | |
| userIp | uip | 지원되지 않음 | 지원되지 않음 | 지원되지 않음 | |
| userLocation | ul | coordinates | False | number[] | Azure Maps 지오코딩 가져오기 API에서 경도 및 위도 형식(경도, 위도)으로 지정된 지구 위 좌표입니다. 이 매개 변수를 지정하면 사용자의 위치가 고려되고, 반환되는 결과는 사용자와 더 관련성이 높아집니다. |
| userMapView | umv | bbox | False | number[] | 경계 상자 개체로 정의된 지구의 직사각형 영역입니다. 사각형의 측면은 경도 및 위도 값(경도1, 위도1, 경도2, 위도2)으로 정의됩니다. 경계 상자를 지정하려면 다음 구문을 사용합니다. 서경도, 남위도, 동경도, 북위도 이 매개 변수를 지정하면 위치 쿼리 결과를 계산할 때 지리적 영역이 고려됩니다. |
| userRegion | ur | 뷰 | False | string | ISO 3166-1 Alpha-2 지역/국가 번호를 나타내는 문자열입니다. 이는 지정된 사용자 지역에 맞게 지정학적 분쟁 국경 및 레이블을 변경합니다. 요청에 정의되지 않은 경우에도 기본적으로 뷰 매개 변수는 자동으로 설정됩니다. 사용 가능한 뷰에 관한 자세한 내용은 지원되는 뷰를 참조하세요. |
Azure Maps 지오코딩 가져오기 API 요청 매개 변수에 관한 자세한 내용은 URI 매개 변수를 참조하세요.
요청 예제
Bing Maps Query로 위치 찾기 API POST 요청:
http://dev.virtualearth.net/REST/v1/Locations/15127 NE 24th Street Redmond WA&key={BingMapsKey}
Azure Maps 지오코딩 가져오기 API POST 요청:
https://atlas.microsoft.com/geocode?api-version=2023-06-01&query=15127 NE 24th Street Redmond WA&subscription-key={Your-Azure-Maps-Subscription-key}
응답 필드
다음 표에는 Bing Maps Query로 위치 찾기 요청 및 이에 상응하는 Azure Maps 요청을 실행할 때 HTTP 응답에 나타날 수 있는 필드가 나열되어 있습니다.
| Bing Maps 필드 | Azure Maps 필드 | 설명 |
|---|---|---|
| 주소: addressLine(JSON) 주소: AddressLine(XML) |
주소: addressLine | |
| 주소: adminDistrict(JSON) 주소: AdminDistrict(XML) |
주소: adminDistricts | |
| 주소: adminDistrict2(JSON) 주소: AdminDistrict2(XML) |
주소: adminDistricts | |
| 주소: countryRegion(JSON) 주소: CountryRegion(XML) |
주소: countryRegion | |
| 주소: countryRegionIso2(JSON) 주소: CountryRegionIso2(XML) |
주소: countryRegion - iso | |
| 주소: neighborhood(JSON) 주소: Neighborhood(XML) |
주소: neighborhood | |
| 주소: formattedAddress(JSON) 주소: FormattedAddress(XML) |
주소: formattedAddress | |
| 주소: locality(JSON) 주소: Locality(XML) |
주소: locality | |
| 주소: postalCode(JSON) 주소: PostalCode(XML) |
주소: postalCode | |
| 주소: Intersection – baseStreet(JSON) 주소: Intersection – BaseStreet(XML) |
주소: intersection -baseStreet | |
| 주소: Intersection – secondaryStreet1(JSON) |
주소: intersection - secondaryStreet1 | |
| 주소: Intersection – secondaryStreet2(JSON) 주소: Intersection – SecondaryStreet2(XML) |
주소: intersection - secondaryStreet2 | |
| 주소: Intersection – intersectionType(JSON) 주소: Intersection – IntersectionType(XML) |
주소: intersection - intersectionType | |
| 주소: Intersection – displayName(JSON) 주소: Intersection – DisplayName(XML) |
주소: intersection - displayName | |
| bbox(JSON) BoundingBox(XML) |
기능: bbox | Bing Maps Query로 위치 찾기 API에서 응답의 좌표는 위도/경도 형식입니다. Azure Maps 지오코딩 가져오기 API의 응답 좌표는 경도/위도 형식입니다(GeoJSON 형식이 사용됨). |
| calculationMethod(JSON) CalculationMethod(XML) |
속성: geocodePoints - calculationMethod | |
| confidence(JSON) Confidence(XML) |
속성: confidence | |
| entityType(JSON) EntityType(XML) |
속성: type | |
| geocodePoints(JSON) GeocodePoint(XML) |
속성: geocodePoints - coordinates | |
| matchCodes(JSON) MatchCode(XML) |
속성: matchCodes | |
| name(JSON) Name(XML) |
지원되지 않음 | formattedAddress는 Azure Maps와 동등합니다. |
| point(JSON) Point(XML) |
기능: coordinates | Bing Maps Query로 위치 찾기 API에서 응답의 좌표는 위도/경도 형식입니다. Azure Maps 지오코딩 가져오기 API의 응답 좌표는 경도/위도 형식입니다(GeoJSON 형식이 사용됨). |
| queryParse(JSON) QueryParse(XML) |
지원되지 않음 | |
| usageTypes(JSON) usageType(XML) |
속성: geocodePoints: usageTypes |
Azure Maps 지오코딩 가져오기 API 응답 필드에 관한 자세한 내용은 정의를 참조하세요.
응답 예
다음 JSON 샘플은 Bing Maps Query로 위치 찾기 요청을 실행할 때 HTTP 응답 본문에 반환되는 내용을 보여줍니다.
{
"authenticationResultCode": "ValidCredentials",
"brandLogoUri": "https://dev.virtualearth.net/Branding/logo_powered_by.png",
"copyright": "Copyright © 2024 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.",
"resourceSets": [
{
"estimatedTotal": 1,
"resources": [
{
"__type": "Location:http://schemas.microsoft.com/search/local/ws/rest/v1",
"bbox": [
47.62649628242932,
-122.14631082421619,
47.634221717570675,
-122.1310271757838
],
"name": "15127 NE 24th St, Redmond, WA 98052",
"point": {
"type": "Point",
"coordinates": [
47.630359,
-122.138669
]
},
"address": {
"addressLine": "15127 NE 24th St",
"adminDistrict": "WA",
"adminDistrict2": "King County",
"countryRegion": "United States",
"formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
"locality": "Redmond",
"postalCode": "98052"
},
"confidence": "High",
"entityType": "Address",
"geocodePoints": [
{
"type": "Point",
"coordinates": [
47.630359,
-122.138669
],
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
]
},
{
"type": "Point",
"coordinates": [
47.630563,
-122.1387383
],
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
]
}
],
"matchCodes": [
"Good"
]
}
]
}
],
"statusCode": 200,
"statusDescription": "OK",
"traceId": "7896468b37528ac145ef77cc62484fd6|MWH0032BE2|0.0.0.1|Ref A: 7D01B283F7644D2891600E265FB30B24 Ref B: CO1EDGE2318 Ref C: 2024-04-23T18:29:55Z"
다음 JSON 샘플은 Azure Maps 지오코딩 가져오기 요청을 실행할 때 HTTP 응답 본문에 반환되는 내용을 보여줍니다.
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-122.138679,
47.630356
]
},
"bbox": [
-122.14632082377759,
47.62649328242932,
-122.1310371762224,
47.634218717570675
],
"properties": {
"type": "Address",
"confidence": "High",
"matchCodes": [
"Good"
],
"geocodePoints": [
{
"calculationMethod": "Rooftop",
"usageTypes": [
"Display"
],
"geometry": {
"type": "Point",
"coordinates": [
-122.138679,
47.630356
]
}
},
{
"calculationMethod": "Rooftop",
"usageTypes": [
"Route"
],
"geometry": {
"type": "Point",
"coordinates": [
-122.138685,
47.6305637
]
}
}
],
"address": {
"addressLine": "15127 NE 24th St",
"postalCode": "98052",
"locality": "Redmond",
"formattedAddress": "15127 NE 24th St, Redmond, WA 98052",
"countryRegion": {
"name": "United States",
"ISO": "US"
},
"adminDistricts": [
{
"shortName": "WA"
},
{
"shortName": "King County"
}
]
}
}
}
]
}
트랜잭션 사용량
Azure Maps의 지오코딩 가져오기 API는 Bing Maps의 Query로 위치 찾기 API와 마찬가지로 요청당 하나의 청구 가능한 트랜잭션을 기록합니다. Azure Maps 트랜잭션에 관한 자세한 내용은 Azure Maps 트랜잭션 이해를 참조하세요.
추가 정보
- 지오코딩 가져오기 일괄 처리: 단일 동기 요청으로 지오코딩 가져오기 API에 일괄 처리 쿼리를 보내는 데 사용됩니다.
지원