Bing Maps 지오코드 데이터 흐름 API 마이그레이션

이 문서에서는 Bing Maps 지오코드 데이터 흐름 API를 Azure Maps 지오코딩 일괄 처리 및 역방향 지오코딩 일괄 처리 API로 마이그레이션하는 방법을 설명합니다. Azure Maps 지오코딩 일괄 처리 API는 단일 API 호출을 통해 일괄 처리 모드에서 거리 주소 또는 장소 이름의 위도 및 경도 좌표를 가져오는 데 사용됩니다. Azure Maps 지오코딩 일괄 처리 API는 단일 요청으로 Azure Maps 지오코딩 API에 일괄 처리 쿼리를 보내는 HTTP POST 요청입니다. Azure Maps 역방향 지오코딩 일괄 처리 API는 위도 및 경도 좌표를 인간이 이해할 수 있는 거리 주소로 변환하는 데 사용됩니다. Azure Maps Reverse 지오코딩 일괄 처리 API는 단일 요청으로 Azure Maps 역방향 지오코딩 가져오기 API에 일괄 처리 쿼리를 보내는 HTTP POST 요청입니다.

필수 조건

• Azure 계정
• Azure Maps 계정
• 구독 키 또는 다른 형태의 Azure Maps를 사용한 인증

주요 차이점

• Bing Maps 지오코드 데이터 흐름 API는 동일한 API 내에서 정방향 및 역방향 일괄 처리 지오코딩을 지원합니다. Azure Maps에는 정방향 및 역방향 지오코딩을 위한 별도의 API가 있습니다.
• Bing Maps 지오코드 데이터 흐름 API를 사용하려면 위치 데이터를 XML 또는 텍스트(csv, 파이프 또는 탭으로 구분) 데이터 파일로 업로드해야 합니다. Azure Maps 지오코딩 일괄 처리 및 역방향 지오코딩 일괄 처리 API는 데이터 파일 업로드 방식을 사용하지 않고 요청 본문에 GeoJSON 형식의 위치 데이터가 포함된 HTTP POST 요청을 사용합니다.
• Bing Maps 지오코드 데이터 흐름 API는 업로드당 최대 200,000개의 엔터티를 지원합니다. Azure Maps 지오코딩 일괄 처리 및 역방향 지오코딩 일괄 처리 API는 동기 요청에서 일괄 처리 쿼리를 최대 100개, 비동기 요청에서 최대 200,000개를 지원합니다.
• Bing Maps 지오코드 데이터 흐름 API에는 상태 및 다운로드 결과를 가져오기 위해 초기 데이터 업로드 이후 일련의 API 호출이 필요합니다. Azure Maps 지오코딩 일괄 처리 및 역방향 지오코딩 일괄 처리 API 동기 요청에는 추가 API 호출이 필요하지 않습니다. 비동기 요청에는 일괄 처리 상태를 가져오고 결과를 다운로드하기 위한 추가 호출이 필요합니다.
• Bing Maps 지오코드 데이터 흐름 좌표는 위도/경도 형식입니다. Azure Maps 지오코딩 일괄 처리 및 역방향 지오코딩 일괄 처리 API 좌표는 GeoJSON 형식이기 때문에 경도/위도 형식입니다.
• 엔터프라이즈용 Bing Maps와 달리 Azure Maps는 유럽(EU) 또는 미국(US) 지리적 영역(geos)으로 데이터 보존을 제한할 수 있는 지리적 범위 지정을 지원하는 글로벌 서비스입니다. 모든 요청(입력 데이터 포함)은 지정된 지리적 영역에서만 처리됩니다. 자세한 내용은 Azure Maps 서비스 지리적 범위를 참조하세요.

보안 및 인증

엔터프라이즈용 Bing Maps는 API 키 인증만 지원합니다. Azure Maps는 구독 키, Microsoft Entra ID 또는 SAS(공유 액세스 서명) 토큰과 같은 API 호출을 인증하는 다양한 방법을 지원합니다. Azure Maps의 보안 및 인증에 대한 자세한 내용은 Azure Maps 지오코딩 일괄 처리 설명서의 Azure Maps를 사용한 인증 및 보안 섹션을 참조하세요.

요청 매개 변수

다음 표에는 Bing Maps 지오코드 데이터 흐름 요청 매개 변수와 이에 상응하는 Azure Maps 매개 변수가 나열되어 있습니다.

Azure Maps URI 매개 변수 및 요청 본문에 대한 자세한 내용은 Azure Maps 지오코딩 일괄 처리 및 역 지오코딩 일괄 처리 설명서를 참조하세요.

Bing Maps 데이터 스키마 2.0 입력 및 출력을 Azure Maps 지오코드 일괄 처리 및 Reverse 지오코드 일괄 처리 API와 비교:

Azure Maps 지오코딩 일괄 처리 응답 필드에 대한 자세한 내용은 정의 응답을 참조하세요.

요청 예제

Bing Maps 지오코드 데이터 흐름 API 요청:

http://spatial.virtualearth.net/REST/v1/Dataflows/Geocode?input=xml&key={BingMapsKey}

지오코드 데이터 흐름 버전 2.0의 샘플 입력 및 출력 데이터를 보여 주는 예는 지오코드 데이터 흐름 샘플 입력 및 출력 데이터 버전 2.0을 참조하세요.

Azure Maps 지오코딩 일괄 처리 API 요청:

POST https://atlas.microsoft.com/geocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}

지오코딩 쿼리를 보내려면 요청 본문에 JSON 형식의 batchItems 배열과 application/json으로 설정된 Content-Type 헤더가 포함된 HTTP POST 요청을 사용합니다.

다음 JSON은 두 개의 지오코딩 쿼리가 포함된 샘플 요청을 보여 줍니다. 한 위치는 구조화되지 않은 형식이고 다른 한 위치는 구조화 형식입니다.

{ 
  "batchItems": [ 
    { 
      "addressLine": "One, Microsoft Way, Redmond, WA 98052", 
      "top": 2 
    }, 
    { 
      "addressLine": "Pike Pl", 
      "adminDistrict": "WA", 
      "locality": "Seattle", 
      "top": 3 
    } 
  ] 
} 

샘플 Azure Maps 역방향 지오코딩 일괄 처리 API 요청:

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01&subscription-key={Your-Azure-Maps-Subscription-key}

역방향 지오코딩 쿼리를 보내려면 요청 본문에 JSON 형식의 batchItems 배열이 포함되어 있고 Content-Type 헤더가 application/json으로 설정된 HTTP POST 요청을 사용합니다.

다음 JSON은 두 개의 역방향 지오코딩 쿼리가 포함된 샘플 요청을 보여 줍니다.

{ 
  "batchItems": [ 
    { 
      "coordinates": [ 
        -122.128275, 
        47.639429 
      ], 
      "resultTypes": [ 
        "Address", 
        "PopulatedPlace" 
      ], 
      "optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B" 
    }, 
    { 
      "coordinates": [ 
        -122.341979399674, 
        47.6095253501216 
      ], 
      "optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7" 
    } 
  ] 
} 

응답 예

Bing Maps 지오코드 데이터 흐름 일괄 작업이 성공적으로 처리되면 지오코드 작업 결과를 다운로드하기 위한 URL이 제공됩니다(완료됨 작업 상태로 표시됨). 성공적인 Bing Maps 지오코드 데이터 흐름 출력의 예는 Bing Maps 설명서의 지오코드 데이터 흐름 샘플 입력 및 출력 데이터 버전 2.0을 참조하세요.

다음 샘플은 Azure Maps 지오코딩 일괄 처리 API 요청을 실행할 때 HTTP 응답 본문에 반환되는 내용을 보여 줍니다.

{ 
  "summary": { 
    "successfulRequests": 1, 
    "totalRequests": 2 
  }, 
  "batchItems": [ 
    {
      "type": "FeatureCollection", 
      "features": [ 
        { 
          "type": "Feature", 
          "properties": { 
            "type": "Address", 
            "confidence": "High", 
            "matchCodes": [ 
              "Good" 
            ], 
            "address": { 
              "locality": "Redmond", 
              "adminDistricts": [ 
                { 
                  "shortName": "WA" 
                }, 
                { 
                  "shortName": "King" 
                } 
              ], 
              "countryRegion": { 
                "ISO": "US", 
                "name": "United States" 
              }, 
              "postalCode": "98052", 
              "formattedAddress": "1 Microsoft Way, Redmond, WA 98052", 
              "addressLine": "1 Microsoft Way" 
            }, 
            "geocodePoints": [ 
              { 
                "geometry": { 
                  "type": "Point", 
                  "coordinates": [ 
                    -122.128275, 
                    47.639429 
                  ] 
                }, 
                "calculationMethod": "Rooftop", 
                "usageTypes": [ 
                  "Display", 
                  "Route" 
                ] 
              }, 
              { 
                "geometry": { 
                  "type": "Point", 
                  "coordinates": [ 
                    -122.127028, 
                    47.638545 
                  ] 
                }, 
                "calculationMethod": "Rooftop", 
                "usageTypes": [ 
                  "Route" 
                ] 
              } 
            ] 
          }, 
          "geometry": { 
            "type": "Point", 
            "coordinates": [ 
              -122.128275, 
              47.639429 
            ] 
          }, 
          "bbox": [ 
            -122.1359181505759, 
            47.63556628242932, 
            -122.1206318494241, 
            47.643291717570676 
          ] 
        } 
      ]
    },
    {
      "error": {
        "code": "Conflicting Parameters",
        "message": "When 'query' is present, only the following parameters are valid: 'bbox, location, view, top'. 'addressLine' was passed"
      }
    }
  ]
}

다음 샘플은 Azure Maps 역방향 지오코딩 일괄 처리 API 요청을 실행할 때 HTTP 응답 본문에 반환되는 내용을 보여 줍니다.

{ 
    "batchItems": [ 
        { 
            "type": "FeatureCollection", 
            "features": [ 
                { 
                    "type": "Feature", 
                    "geometry": { 
                        "type": "Point", 
                        "coordinates": [ 
                            -122.1294081, 
                            47.6391325 
                        ] 
                    }, 
                    "properties": { 
                        "geocodePoints": [ 
                            { 
                                "geometry": { 
                                    "type": "Point", 
                                    "coordinates": [ 
                                        -122.1294081, 
                                        47.6391325 
                                    ] 
                                }, 
                                "calculationMethod": "Rooftop", 
                                "usageTypes": [ 
                                    "Display" 
                                ] 
                            } 
                        ], 
                        "address": { 
                            "addressLine": "15770 NE 31st St", 
                            "adminDistricts": [ 
                                { 
                                    "shortName": "WA" 
                                }, 
                                { 
                                    "shortName": "King Co." 
                                } 
                            ], 
                            "countryRegion": { 
                                "name": "United States", 
                                "iso": "US" 
                            }, 
                            "locality": "Redmond", 
                            "neighborhood": "Overlake", 
                            "postalCode": "98052", 
                            "formattedAddress": "15770 NE 31st St, Redmond, WA 98052, United States" 
                        }, 
                        "confidence": "High", 
                        "matchCodes": [ 
                            "Good" 
                        ], 
                        "type": "Address" 
                    }, 
                    "bbox": [ 
                        -122.13705120720665, 
                        47.635269782429326, 
                        -122.12176499279336, 
                        47.64299521757068 
                    ] 
                } 
            ] 
        }, 
        { 
            "type": "FeatureCollection", 
            "features": [ 
                { 
                    "type": "Feature", 
                    "geometry": { 
                        "type": "Point", 
                        "coordinates": [ 
                            -122.341979399674, 
                            47.6095253501216 
                        ] 
                    }, 
                    "properties": { 
                        "geocodePoints": [ 
                            { 
                                "geometry": { 
                                    "type": "Point", 
                                    "coordinates": [ 
                                        -122.341979399674, 
                                        47.6095253501216 
                                    ] 
                                }, 
                                "calculationMethod": "Interpolation", 
                                "usageTypes": [ 
                                    "Display", 
                                    "Route" 
                                ] 
                            } 
                        ], 
                        "address": { 
                            "addressLine": "1736 Pike Pl", 
                            "adminDistricts": [ 
                                { 
                                    "shortName": "WA"
                                }, 
                                { 
                                    "shortName": "King Co." 
                                } 
                            ], 
                            "countryRegion": { 
                                "name": "United States", 
                                "iso": "US" 
                            }, 
                            "intersection": { 
                                "baseStreet": "Pike Pl", 
                                "displayName": "Pike Pl and Stewart St", 
                                "intersectionType": "Near", 
                                "secondaryStreet1": "Stewart St", 
                                "secondaryStreet2": null 
                            }, 
                            "locality": "Seattle", 
                            "neighborhood": "Downtown Seattle", 
                            "postalCode": "98101", 
                            "formattedAddress": "1736 Pike Pl, Seattle, WA 98101, United States" 
                        }, 
                        "confidence": "Medium", 
                        "matchCodes": [ 
                            "Good" 
                        ], 
                        "type": "Address" 
                    }, 
                    "bbox": [ 
                        -122.34961817972945, 
                        47.605662632550924, 
                        -122.33434061961856, 
                        47.61338806769228 
                    ] 
                } 
            ] 
        } 
    ], 
    "summary": { 
        "successfulRequests": 2, 
        "totalRequests": 2 
    } 
} 

트랜잭션 사용량

Bing Maps 지오코드 데이터 흐름 API와 마찬가지로 Azure Maps 지오코딩 일괄 처리 및 역방향 지오코딩 일괄 처리 API는 지오코딩된 항목당 하나의 청구 가능한 트랜잭션을 기록합니다. 예를 들어, 일괄 처리 요청에 지오코딩된 100개의 위치는 100개의 청구 가능한 트랜잭션으로 이어집니다. Azure Maps 트랜잭션에 대한 자세한 내용은 Azure Maps 트랜잭션 이해를 참조하세요.

추가 정보

추가 Azure Maps 지오코딩 API

• 지오코딩 가져오기: 거리 주소나 장소 이름의 위도 및 경도 좌표를 가져오는 데 사용합니다.
• 역방향 지오코딩 가져오기: 위도 및 경도 좌표에서 거리 주소와 위치 정보를 가져오는 데 사용합니다.

지원

• Microsoft Q&A 포럼