Search - Get Reverse Geocoding Batch

단일 요청으로 Reverse Geocoding API에 쿼리 배치를 보내는 데 사용합니다.

API는 단일 요청을 사용하여 역방향 지오코딩 API를 위해 최대 100개의 쿼리 일괄 처리를 보내는 HTTP 요청입니다.

동기 일괄 처리 요청 제출

간단한 일괄 처리 요청에는 동기 API를 사용하는 것이 좋습니다. 서비스가 요청을 받으면 일괄 처리 항목이 계산되는 즉시 응답하며 나중에 결과를 검색할 가능성이 없습니다. 요청이 60초보다 오래 걸리는 경우 동기 API는 시간 제한 오류(408 응답)를 반환합니다. 일괄 처리 항목 수는 이 API에 대해 100개 제한됩니다.

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2023-06-01

Batch 요청에 대한 POST 본문

역방향 지오코딩 쿼리를 보내려면 요청 본문에 POST 배열이 batchItems 형식으로 포함되고 json 헤더가 Content-Type설정되는 application/json 요청을 사용합니다. 다음은 2개의 역방향 지오코딩 쿼리를 포함하는 샘플 요청 본문입니다.

{
  "batchItems": [
    {
      "coordinates": [-122.128275, 47.639429],
      "resultTypes": ["Address", "PopulatedPlace"]
    },
    {
      "coordinates": [-122.341979399674, 47.6095253501216]
    }
  ]
}

역방향 지오코딩 batchItem 개체는 지원되는 역방향 지오코딩URI 매개 변수수락할 수 있습니다.

일괄 처리에는 1개 이상의 쿼리가 포함되어야 합니다.

Batch 응답 모델

일괄 처리 응답에는 원래 일괄 처리 요청의 일부인 summary 성공적으로 실행된 쿼리와 totalRequests 나타내는 successfulRequests 구성 요소가 포함되어 있습니다. 일괄 처리 응답에는 일괄 처리 요청의 모든 쿼리에 대한 응답이 포함된 batchItems 배열도 포함됩니다. batchItems 일괄 처리 요청에서 원래 쿼리가 전송된 순서와 정확히 동일한 순서로 결과를 포함합니다. 각 항목은 다음 유형 중 하나입니다.

• GeocodingResponse - 쿼리가 성공적으로 완료된 경우

• Error - 쿼리가 실패한 경우 응답에는 이 경우 code 및 message 포함됩니다.

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2025-01-01

URI 매개 변수

요청 헤더

요청 본문

응답

보안

AADToken

다음은 Microsoft Entra OAuth 2.0 흐름에 . Azure 역할 기반 액세스 컨트롤과 쌍을 이루는 경우 Azure Maps REST API에 대한 액세스를 제어하는 데 사용할 수 있습니다. Azure 역할 기반 액세스 제어는 하나 이상의 Azure Maps 리소스 계정 또는 하위 리소스에 대한 액세스를 지정하는 데 사용됩니다. 모든 사용자, 그룹 또는 서비스 주체는 Azure Maps REST API에 대한 하나 이상의 권한으로 구성된 기본 제공 역할 또는 사용자 지정 역할을 통해 액세스 권한을 부여할 수 있습니다.

시나리오를 구현하려면인증 개념을 확인하는 것이 좋습니다. 요약하자면, 이 보안 정의는 특정 API 및 범위에 대한 액세스 제어가 가능한 개체를 통해 애플리케이션을 모델링하기 위한 솔루션을 제공합니다.

형식: oauth2
Flow: implicit
권한 부여 URL: https://login.microsoftonline.com/common/oauth2/authorize

범위

subscription-key

Azure Portal, PowerShell, CLI, Azure SDK 또는 REST API를 통해 Azure 관리 평면을 통해 Azure Maps 리소스를 만들 때 프로비전되는 공유 키입니다.

이 키를 사용하면 모든 애플리케이션이 모든 REST API에 액세스할 수 있는 권한이 부여됩니다. 즉, 이러한 키는 현재 발급된 계정의 마스터 키로 처리될 수 있습니다.

공개적으로 노출된 애플리케이션의 경우 이 키를 안전하게 저장할 수 있는 Azure Maps REST API의 서버-서버 액세스를 사용하는 것이 좋습니다.

형식: apiKey
In(다음 안에): header

SAS Token

공유 액세스 서명 토큰은 Azure Portal, PowerShell, CLI, Azure SDK 또는 REST API를 통해 Azure 관리 평면을 통해 Azure Maps 리소스의 SAS 나열 작업에서 만들어집니다.

이 토큰을 사용하면 모든 애플리케이션이 Azure 역할 기반 액세스 제어를 사용하여 액세스하고 특정 토큰에 사용할 만료, 속도 및 지역에 대한 세분화된 제어 권한을 부여받습니다. 즉, SAS 토큰을 사용하여 애플리케이션이 공유 키보다 더 보안이 유지되는 방식으로 액세스를 제어할 수 있습니다.

공개적으로 노출된 애플리케이션의 경우 렌더링 남용을 제한하고 정기적으로 SAS 토큰을 갱신하도록 맵 계정 리소스 허용된 원본의 특정 목록을 구성하는 것이 좋습니다.

형식: apiKey
In(다음 안에): header

예제

A Reverse Geocoding Batch API call containing 2 Reverse Geocoding queries

POST https://atlas.microsoft.com/reverseGeocode:batch?api-version=2025-01-01

{
  "batchItems": [
    {
      "coordinates": [
        -122.138681,
        47.630358
      ],
      "resultTypes": [
        "Address",
        "PopulatedPlace"
      ],
      "optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
    },
    {
      "coordinates": [
        47.630358,
        -122.138681
      ],
      "optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
    }
  ]
}

{
  "summary": {
    "successfulRequests": 1,
    "totalRequests": 2
  },
  "batchItems": [
    {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {
            "type": "Address",
            "confidence": "Medium",
            "matchCodes": [
              "Good"
            ],
            "address": {
              "locality": "Redmond",
              "adminDistricts": [
                {
                  "name": "Washington",
                  "shortName": "WA"
                },
                {
                  "name": "King County",
                  "shortName": "King Co."
                }
              ],
              "countryRegion": {
                "ISO": "US",
                "name": "United States"
              },
              "postalCode": "98052",
              "formattedAddress": "2267 152nd Ave NE, Redmond, Washington 98052, United States",
              "streetName": "152nd Ave NE",
              "streetNumber": "2267",
              "addressLine": "2267 152nd Ave NE"
            },
            "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
          ]
        }
      ],
      "optionalId": "4C3681A6C8AA4AC3441412763A2A25C81444DC8B"
    },
    {
      "error": {
        "code": "Bad Request",
        "message": "The provided coordinates (-122.138681,47.630358) in coordinates field are invalid or out of range"
      },
      "optionalId": "6M9W39P12SNHGAIZ4JQ7F57NWJLV2BRYEQRD7OH7"
    }
  ]
}

정의

Address

결과의 주소입니다.

AdminDistricts

주소에 대한 국가 또는 지역의 세분화 이름입니다. 이 요소는 일반적으로 첫 번째 순서 관리 세분화로 처리되지만 경우에 따라 국가, 종속성 또는 지역의 두 번째, 세 번째 또는 네 번째 순서 세분화도 포함됩니다.

CalculationMethodEnum

지오코드 지점을 계산하는 데 사용된 메서드입니다.

ConfidenceEnum

지오코딩된 위치 결과가 일치하는 신뢰도 수준입니다. 일치 코드와 함께 이 값을 사용하여 일치 항목에 대한 자세한 정보를 확인합니다.

지오코딩된 위치의 신뢰도는 지정된 경우 지오코딩된 위치 및 사용자의 위치의 상대적 중요도를 비롯한 여러 요인을 기반으로 합니다.

CountryRegion

ErrorAdditionalInfo

리소스 관리 오류 추가 정보입니다.

ErrorDetail

오류 세부 정보입니다.

ErrorResponse

오류 응답

FeatureCollectionEnum

FeatureCollection 개체의 형식은 FeatureCollection이어야 합니다.

FeaturesItem

FeatureTypeEnum

기능 유형은 기능이어야 합니다.

GeocodePoints

계산 방법과 제안된 용도가 다른 지오코드 지점의 컬렉션입니다.

GeocodingBatchResponse

이 개체는 성공적인 Geocoding Batch 서비스 호출에서 반환됩니다.

GeocodingBatchResponseItem

GeoJsonPoint

유효한 GeoJSON Point 기하 도형 형식입니다. 자세한 내용은 RFC 7946 참조하세요.

Intersection

결과의 주소입니다.

MatchCodesEnum

응답의 각 위치에 대한 지오코딩 수준을 나타내는 하나 이상의 일치 코드 값입니다.

예를 들어 Good 및 Ambiguous 일치 코드가 있는 지오코딩된 위치는 위치 정보에 대해 둘 이상의 지오코드 위치를 찾았으며 지오코드 서비스에 일치 항목을 찾기 위한 검색 업 계층 구조가 없음을 의미합니다.

마찬가지로, Ambiguous 및 UpHierarchy 일치 코드가 있는 지오코딩된 위치는 제공된 모든 위치 정보와 일치하는 지오코드 위치를 찾을 수 없음을 의미하므로 지오코드 서비스는 업 계층 구조를 검색하고 해당 수준에서 여러 일치 항목을 발견해야 했습니다. Ambiguous 및 UpHierarchy 결과의 예는 전체 주소 정보를 제공하지만 지오코드 서비스에서 도로 주소에 대한 일치 항목을 찾을 수 없고 대신 둘 이상의 RoadBlock 값에 대한 정보를 반환하는 경우입니다.

가능한 값은 다음과 같습니다.

Good: 위치에 일치하는 항목이 하나만 있거나 반환된 모든 일치 항목이 강력한 일치 항목으로 간주됩니다. 예를 들어 뉴욕 쿼리는 몇 가지 좋은 일치 항목을 반환합니다.

Ambiguous: 위치는 가능한 일치 항목 집합 중 하나입니다. 예를 들어 거리 주소 128 Main St.를 쿼리할 때 선택할 옵션을 결정하는 데 충분한 정보가 없기 때문에 응답은 128 North Main St. 및 128 South Main St.에 대한 두 위치를 반환할 수 있습니다.

UpHierarchy: 위치는 지리적 계층 구조 위로의 이동을 나타냅니다. 이는 위치 요청에 대한 일치 항목을 찾을 수 없으므로 덜 정확한 결과가 반환될 때 발생합니다. 예를 들어 요청된 주소에 대한 일치 항목을 찾을 수 없는 경우 RoadBlock 엔터티 형식이 있는 UpHierarchy 일치 코드가 반환될 수 있습니다.

Properties

ResultTypeEnum

응답에서 원하는 엔터티 형식을 지정합니다. 지정한 형식만 반환됩니다. 지정한 엔터티 형식에 지점을 매핑할 수 없는 경우 응답에 위치 정보가 반환되지 않습니다. 기본값은 가능한 모든 엔터티입니다. 다음 옵션에서 선택한 엔터티 형식의 쉼표로 구분된 목록입니다.

• 주소
• 이웃
• PopulatedPlace
• Postcode1
• AdminDivision1
• AdminDivision2
• 국가/지역

이러한 엔터티 형식은 가장 구체적인 엔터티에서 최소 특정 엔터티로 정렬됩니다. 둘 이상의 엔터티 형식의 엔터티가 발견되면 가장 구체적인 엔터티만 반환됩니다. 예를 들어 Address 및 AdminDistrict1을 엔터티 형식으로 지정하고 두 형식 모두에 대해 엔터티를 찾은 경우 주소 엔터티 정보만 응답에 반환됩니다.

ReverseGeocodingBatchRequestBody

처리할 역방향 지오코딩 쿼리/요청 목록입니다. 목록에는 최대 100개의 쿼리가 포함될 수 있으며 1개 이상의 쿼리가 포함되어야 합니다.

ReverseGeocodingBatchRequestItem

Batch 쿼리 개체

Summary

일괄 처리 요청에 대한 요약

UsageTypeEnum

지오코드 지점에 가장 적합합니다. 각 지오코드 지점은 Route 지점, Display 지점 또는 둘 다로 정의됩니다. 위치에 대한 경로를 만드는 경우 Route 지점을 사용합니다. 지도에 위치를 표시하는 경우 Display 지점을 사용합니다. 예를 들어 위치가 공원인 경우 Route 지점은 자동차로 들어갈 수 있는 공원 입구를 지정할 수 있으며, Display 지점은 공원의 중심을 지정하는 지점일 수 있습니다.