Microsoft Azure Geocode API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Geocode API
tags:
- name: Geocode
paths:
  /geocode:
    get:
      description: '**Geocoding**<br><br>**Applies to:** see pricing [tiers](https://aka.ms/AzureMapsPricingTier).<br><br>In many cases, the complete search service might be too much, for instance if you are only interested in traditional geocoding. Search can also be accessed for address look up exclusively. The geocoding is performed by hitting the geocoding endpoint with just the address or partial address in question. The geocoding search index will be queried for everything above the street level data. No POIs will be returned. Note that the geocoder is very tolerant of typos and incomplete addresses. It will also handle everything from exact street addresses or street or intersections as well as higher level geographies such as city centers, counties, states etc.<br>>[!Important]<br>>By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional details.'
      operationId: microsoftAzureSearchGetgeocoding
      x-ms-examples:
        Search detail address 15127 NE 24th Street, Redmond, WA:
          $ref: ./examples/ForwardGeocoding.json
        Search detail address 15127 NE 24th Street, Redmond, WA by addressLine:
          $ref: ./examples/ForwardGeocodingByAddressLine.json
        Search detail address 15127 NE 24th Street, Redmond, WA by query:
          $ref: ./examples/ForwardGeocodingByQuery.json
        Search landmark Empire State Building by query:
          $ref: ./examples/ForwardGeocodingFindLandmarkByQuery.json
      parameters:
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/Accept-Language'
      - $ref: '#/components/parameters/Top'
      - name: query
        in: query
        description: A string that contains information about a location, such as an address or landmark name.
        required: false
        schema:
          type: string
      - name: addressLine
        in: query
        description: 'The official street line of an address relative to the area, as specified by the locality, or postalCode, properties. Typical use of this element would be to provide a street address or any official address.


          **If query is given, should not use this parameter.**'
        required: false
        schema:
          type: string
      - name: countryRegionSet
        in: query
        description: 'Comma separated string of country or region codes(ISO 3166-1 Alpha-2), e.g. FR,ES. This will limit the search to the specified countries. Only the first country code will be used for the Geocoder.


          **If query is given, should not use this parameter.**'
        required: false
        x-ms-parameter-location: method
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
      - $ref: '#/components/parameters/Bbox'
      - $ref: '#/components/parameters/View'
      - $ref: '#/components/parameters/Location'
      - name: adminDistrict
        in: query
        description: 'The country subdivision portion of an address, such as WA.


          **If query is given, should not use this parameter.**'
        required: false
        schema:
          type: string
      - name: adminDistrict2
        in: query
        description: 'The county for the structured address, such as King.


          **If query is given, should not use this parameter.**'
        required: false
        schema:
          type: string
      - name: adminDistrict3
        in: query
        description: 'The named area for the structured address.


          **If query is given, should not use this parameter.**'
        required: false
        schema:
          type: string
      - name: locality
        in: query
        description: 'The locality portion of an address, such as Seattle.


          **If query is given, should not use this parameter.**'
        required: false
        schema:
          type: string
      - name: postalCode
        in: query
        description: 'The postal code portion of an address.


          **If query is given, should not use this parameter.**'
        required: false
        schema:
          type: string
      - name: strictMatch
        in: query
        description: 'Restrict the geocoding result to the country or region that is specified in the countryRegionSet field and the state, province or territory specified in the adminDistrict field.


          **If query is given, should not use this parameter.**'
        required: false
        x-ms-enum:
          name: StrictMatchEnum
          modelAsString: true
          values:
          - name: NotStrict
            value: notstrict
            description: Do not restrict results to the specified countryRegionSet and adminDistrict.
          - name: Strict
            value: strict
            description: Restrict results to the specified countryRegionSet and adminDistrict.
        x-ms-parameter-location: method
        schema:
          type: string
          enum:
          - notstrict
          - strict
          default: notstrict
      - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
      responses:
        '200':
          description: OK
          headers:
            x-ms-request-id:
              description: request id.
              schema:
                type: string
          content:
            application/geo+json:
              schema:
                $ref: '#/components/schemas/GeocodingResponse'
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      summary: Microsoft Azure Get Geocode
      tags:
      - Geocode
  /geocode/batch:
    post:
      description: '**Geocoding Batch API**<br><br><br>**Applies to**: see pricing [tiers](https://aka.ms/AzureMapsPricingTier).<br><br><br><br>The Geocoding Batch API sends batches of queries to [Geocoding API](https://docs.microsoft.com/rest/api/maps/search-v2/get-geocoding) using just a single API call. The API allows caller to batch up to **100** queries.<br>>[!Important]<br>>By using this feature, you agree to the preview legal terms. See the [Preview Supplemental Terms](https://azure.microsoft.com/support/legal/preview-supplemental-terms/) for additional details.<br><br>### Submit Synchronous Batch Request<br>The Synchronous API is recommended for lightweight batch requests. When the service receives a request, it will respond as soon as the batch items are calculated and there will be no possibility to retrieve the results later. The Synchronous API will return a timeout error (a 408 response) if the request takes longer than 60 seconds. The number of batch items is limited to **100** for this API.<br>```<br>POST https://atlas.microsoft.com/geocode/batch?api-version=2022-02-01-preview<br>```<br>### POST Body for Batch Request<br>To send the _geocoding_ queries you will use a `POST` request where the request body will contain the `batchItems` array in `json` format and the `Content-Type` header will be set to `application/json`. Here''s a sample request body containing 2 _geocoding_ queries:<br><br><br>```<br>{<br>  "batchItems": [<br>    {<br>      "addressLine": "One, Microsoft Way, Redmond, WA 98052",<br>      "top": 2<br>    },<br>    {<br>      "addressLine": "Pike Pl",<br>      "adminDistrict": "WA",<br>      "locality": "Seattle",<br>      "top": 3<br>    }<br>  ]<br>}<br>```<br><br>A _geocoding_ batchItem object can accept any of the supported _geocoding_ [URI parameters](https://docs.microsoft.com/rest/api/maps/search-v2/get-geocoding#uri-parameters) except query.<br><br><br>The batch should contain at least **1** query.<br><br><br>### Batch Response Model<br>The batch response contains a `summary` component that indicates the `totalRequests` that were part of the original batch request and `successfulRequests` i.e. queries which were executed successfully. The batch response also includes a `batchItems` array which contains a response for each and every query in the batch request. The `batchItems` will contain the results in the exact same order the original queries were sent in the batch request. Each item is of one of the following types:<br><br>  - [`GeocodingResponse`](https://docs.microsoft.com/rest/api/maps/search-v2/get-geocoding#geocodingresponse) - If the query completed successfully.<br><br>  - `Error` - If the query failed. The response will contain a `code` and a `message` in this case.<br><br><br>'
      operationId: microsoftAzureSearchGetgeocodingbatch
      x-ms-examples:
        A Geocoding Batch API call containing 2 Geocoding queries:
          $ref: ./examples/ForwardGeocodingBatch.json
      parameters:
      - $ref: ../../../Common/preview/1.0/common.json#/parameters/ClientId
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/Accept-Language'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodingBatchResponse'
        '206':
          description: Partial Content. Api would return 206 when part of the batchItem fail to get a response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodingBatchResponse'
        default:
          $ref: ../../../Common/preview/1.0/common.json#/responses/default
      summary: Microsoft Azure Post Geocode Batch
      tags:
      - Geocode
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeocodingBatchRequestBody'
        description: The list of address geocoding queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query.
        required: true
components:
  schemas:
    GeocodingBatchRequestBody:
      description: The list of address geocoding queries/requests to process. The list can contain a max of 100 queries and must contain at least 1 query.
      type: object
      properties:
        batchItems:
          description: The list of queries to process.
          type: array
          items:
            $ref: '#/components/schemas/GeocodingBatchRequestItem'
    GeocodingBatchRequestItem:
      description: Batch Query object
      type: object
      properties:
        optionalId:
          description: id of the request which would show in corresponding batchItem
          type: string
        top:
          description: 'Maximum number of responses that will be returned. Default: 5, minimum: 1 and maximum: 20.'
          type: integer
          default: 5
          minimum: 1
          maximum: 20
        addressLine:
          description: The official street line of an address relative to the area, as specified by the locality, or postalCode, properties. Typical use of this element would be to provide a street address or any official address.
          type: string
        countryRegionSet:
          description: Comma separated string of country or region codes, e.g. FR,ES. This will limit the search to the specified countries. Only the first country code will be used for the Geocoder.
          type: array
          items:
            type: string
        bbox:
          description: 'A rectangular area on the earth defined as a bounding box object. The sides of the rectangles are defined by latitude and longitude values. For more information, see Location and Area Types. When you specify this parameter, the geographical area is taken into account when computing the results of a location query.


            Example: [lon1, lat1, lon2, lat2]'
          type: array
          items:
            type: number
            format: double
          minItems: 4
          maxItems: 4
        view:
          description: A string that specifies an [ISO 3166-1 Alpha-2 region/country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). This will alter Geopolitical disputed borders and labels to align with the specified user region.
          type: string
        location:
          description: 'A point on the earth specified as a latitude and longitude. When you specify this parameter, the user’s location is taken into account and the results returned may be more relevant to the user. Example: &location=lon,lat'
          type: array
          items:
            type: number
            format: double
          minItems: 2
          maxItems: 2
        adminDistrict:
          description: The country subdivision portion of an address, such as WA.
          type: string
        adminDistrict2:
          description: The county for the structured address, such as King.
          type: string
        adminDistrict3:
          description: The named area for the structured address.
          type: string
        locality:
          description: The locality portion of an address, such as Seattle.
          type: string
        postalCode:
          description: The postal code portion of an address.
          type: string
        strictMatch:
          description: Restrict the geocoding result to the country or region that is specified in the countryRegion field and the state, province or territory specified in the adminDistrict field.
          type: string
          default: notstrict
          enum:
          - notstrict
          - strict
          x-ms-enum:
            name: StrictMatchEnum
            modelAsString: true
            values:
            - value: notstrict
              description: Do not restrict results to the specified countryRegion and adminDistrict.
            - value: strict
              description: Restrict results to the specified countryRegion and adminDistrict.
    GeocodingResponse:
      description: This object is returned from a successful Geocoding call
      type: object
      properties:
        type:
          $ref: '#/components/schemas/FeatureType'
        features:
          $ref: '#/components/schemas/Features'
        nextLink:
          $ref: '#/components/schemas/NextLink'
    Features:
      type: array
      items:
        $ref: '#/components/schemas/FeaturesItem'
    GeoJSONPoint:
      type: object
      description: A structure for Point Geometry
      properties:
        type:
          description: Specifies the `type` for the geometry. Value should always be equal to "Point".
          type: string
          enum:
          - Point
          x-ms-enum:
            name: GeoJSONPointTypeEnum
            modelAsString: true
            values:
            - value: Point
        coordinates:
          description: Coordinates for the `Point` geometry.
          type: array
          minItems: 2
          maxItems: 2
          items:
            type: number
            format: double
    GeocodingBatchResponseItem:
      type: object
      properties:
        optionalId:
          description: id of the batchItem which would be the same as the id in the request
          type: string
        type:
          $ref: '#/components/schemas/FeatureType'
        features:
          $ref: '#/components/schemas/Features'
        nextLink:
          $ref: '#/components/schemas/NextLink'
        error:
          $ref: ../../../../../common-types/data-plane/v1/types.json#/definitions/ErrorDetail
    NextLink:
      type: string
      description: The is the link to the next page of the features returned. If it's the last page, no this field.
    GeocodingBatchResponse:
      description: This object is returned from a successful Geocoding Batch service call.
      type: object
      properties:
        summary:
          description: Summary for the batch request
          type: object
          readOnly: true
          properties:
            successfulRequests:
              description: Number of successful requests in the batch
              type: integer
              readOnly: true
            totalRequests:
              description: Total number of requests in the batch
              type: integer
              readOnly: true
        batchItems:
          description: Array containing the batch results.
          type: array
          items:
            $ref: '#/components/schemas/GeocodingBatchResponseItem'
    UsageType:
      type: string
      enum:
      - Display
      - Route
    GeocodePoints:
      description: A collection of geocode points that differ in how they were calculated and their suggested use.
      type: array
      items:
        type: object
        properties:
          geometry:
            $ref: '#/components/schemas/GeoJSONPoint'
          calculationMethod:
            description: 'The method that was used to compute the geocode point.

              - `Interpolation`: The geocode point was matched to a point on a road using interpolation.

              - `InterpolationOffset`: The geocode point was matched to a point on a road using interpolation with an additional offset to shift the point to the side of the street.

              - `Parcel`: The geocode point was matched to the center of a parcel.

              - `Rooftop`: The geocode point was matched to the rooftop of a building.'
            type: string
            enum:
            - Interpolation
            - InterpolationOffset
            - Parcel
            - Rooftop
          usageTypes:
            description: 'The best use for the geocode point.

              Each geocode point is defined as a `Route` point, a `Display` point or both.

              Use `Route` points if you are creating a route to the location. Use `Display` points if you are showing the location on a map. For example, if the location is a park, a `Route` point may specify an entrance to the park where you can enter with a car, and a `Display` point may be a point that specifies the center of the park.'
            type: array
            items:
              $ref: '#/components/schemas/UsageType'
    MatchCodes:
      description: 'One or more match code values that represent the geocoding level for each location in the response.


        For example, a geocoded location with match codes of `Good` and `Ambiguous` means that more than one geocode location was found for the location information and that the geocode service did not have search up-hierarchy to find a match.


        Similarly, a geocoded location with match codes of `Ambiguous` and `UpHierarchy` implies that a geocode location could not be found that matched all the provided location information, so the geocode service had to search up-hierarchy and found multiple matches at that level. An example of up an `Ambiguous` and `UpHierarchy` result is when you provide complete address information, but the geocode service cannot locate a match for the street address and instead returns information for more than one RoadBlock value.


        The possible values are:


        `Good`: The location has only one match or all returned matches are considered strong matches. For example, a query for New York returns several Good matches.


        `Ambiguous`: The location is one of a set of possible matches. For example, when you query for the street address 128 Main St., the response may return two locations for 128 North Main St. and 128 South Main St. because there is not enough information to determine which option to choose.


        `UpHierarchy`: The location represents a move up the geographic hierarchy. This occurs when a match for the location request was not found, so a less precise result is returned. For example, if a match for the requested address cannot be found, then a match code of `UpHierarchy` with a RoadBlock entity type may be returned.'
      type: array
      items:
        type: string
        enum:
        - Good
        - Ambiguous
        - UpHierarchy
    Bbox:
      description: Information on the coordinate range for point Geometry.  Please refer to [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946#section-5) for details.
      type: array
      minItems: 4
      maxItems: 4
      items:
        type: number
        format: double
    FeatureType:
      type: string
      enum:
      - FeatureCollection
    Confidence:
      description: 'The level of confidence that the geocoded location result is a match. Use this value with the match code to determine for more complete information about the match.


        The confidence of a geocoded location is based on many factors including the relative importance of the geocoded location and the user’s location, if specified. The following description provides more information about how confidence scores are assigned and how results are ranked.


        If the confidence is set to `High`, one or more strong matches were found. Multiple `High` confidence matches are sorted in ranked order by importance when applicable. For example, landmarks have importance but addresses do not.


        If a request includes a location or a view, then the ranking may change appropriately. For example, a location query for "Paris" returns "Paris, France" and "Paris, TX" both with `High` confidence. "Paris, France" is always ranked first due to importance unless a user location indicates that the user is in or very close to Paris, TX or the map view indicates that the user is searching in that area.


        In some situations, the returned match may not be at the same level as the information provided in the request. For example, a request may specify address information and the geocode service may only be able to match a postal code. In this case, if the geocode service has a confidence that the postal code matches the data, the confidence is set to `Medium` and the match code is set to `UpHierarchy` to specify that it could not match all of the information and had to search up-hierarchy.


        If the location information in the query is ambiguous, and there is no additional information to rank the locations (such as user location or the relative importance of the location), the confidence is set to `Medium`. For example, a location query for "148th Ave, Bellevue" may return "148th Ave SE" and "148th Ave NE" both with `Medium` confidence.


        If the location information in the query does not provide enough information to geocode a specific location, a less precise location value may be returned and the confidence is set to `Medium`. For example, if an address is provided, but a match is not found for the house number, the geocode result with a Roadblock entity type may be returned.'
      type: string
      enum:
      - High
      - Medium
      - Low
    FeaturesItem:
      type: object
      properties:
        type:
          type: string
          description: must be Feature
          enum:
          - Feature
          x-ms-enum:
            name: FeaturesItemTypeEnum
            modelAsString: true
            values:
            - value: Feature
        id:
          type: string
          description: ID for feature returned
        properties:
          type: object
          properties:
            type:
              type: string
              description: "One of: \n* Address\n* RoadBlock\n* RoadIntersection"
              readOnly: true
            confidence:
              $ref: '#/components/schemas/Confidence'
            matchCodes:
              $ref: '#/components/schemas/MatchCodes'
            address:
              $ref: '#/components/schemas/Address'
            geocodePoints:
              $ref: '#/components/schemas/GeocodePoints'
        geometry:
          $ref: '#/components/schemas/GeoJSONPoint'
        bbox:
          $ref: '#/components/schemas/Bbox'
    Address:
      description: The address of the result
      type: object
      properties:
        addressLine:
          description: AddressLine that includes Street Name and Number
          type: string
          readOnly: true
        locality:
          description: locality property
          type: string
          readOnly: true
        neighborhood:
          description: neighborhood property
          type: string
          readOnly: true
        adminDistricts:
          description: The subdivision name in the country or region for an address. This element is typically treated as the first order administrative subdivision, but in some cases it also contains the second, third, or fourth order subdivision in a country, dependency, or region.
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: "The name for the corresponding adminDistrict field, \nFor adminDistrict[0], this could be full name of state such as Washington, \nFor adminDistrict[1], this could be the full name of the county"
              shortName:
                type: string
                description: "The short name for the corresponding adminDistrict field, \nFor adminDistrict[0], this could be short name of state such as WA, \nFor adminDistrict[1], this could be the short name of the county"
        postalCode:
          description: Postal Code property
          type: string
          readOnly: true
        countryRegion:
          type: object
          properties:
            ISO:
              description: ISO of country/region
              type: string
              readOnly: true
            name:
              description: name of country/region
              type: string
              readOnly: true
        formattedAddress:
          description: Formatted Address property
          type: string
          readOnly: true
  parameters:
    Accept-Language:
      name: Accept-Language
      in: header
      description: "Language in which search results should be returned. \n\nPlease refer to [Supported Languages](https://learn.microsoft.com/azure/azure-maps/supported-languages) for details."
      required: false
      x-ms-parameter-location: client
      schema:
        type: string
    Bbox:
      name: bbox
      in: query
      description: 'A rectangular area on the earth defined as a bounding box object. The sides of the rectangles are defined by latitude and longitude values. When you specify this parameter, the geographical area is taken into account when computing the results of a location query.


        Example: lon1,lat1,lon2,lat2'
      required: false
      x-ms-parameter-location: method
      style: form
      explode: false
      schema:
        type: array
        items:
          type: number
          format: double
        maxItems: 4
        minItems: 4
    View:
      name: view
      in: query
      description: A string that an [ISO 3166-1 Alpha-2 region/country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). This will alter Geopolitical disputed borders and labels to align with the specified user region.
      required: false
      x-ms-parameter-location: method
      schema:
        type: string
    Location:
      name: location
      in: query
      description: 'A point on the earth specified as a latitude and longitude. When you specify this parameter, the user’s location is taken into account and the results returned may be more relevant to the user. Example: &location=lon,lat'
      required: false
      x-ms-parameter-location: method
      style: form
      explode: false
      schema:
        type: array
        items:
          type: number
          format: double
        maxItems: 2
        minItems: 2
    Top:
      name: top
      in: query
      description: 'Maximum number of responses that will be returned. Default: 5, minimum: 1 and maximum: 20.'
      required: false
      x-ms-parameter-location: method
      schema:
        type: integer
        default: 5
        maximum: 20
        minimum: 1
    ApiVersion:
      name: api-version
      description: Version number of Azure Maps API.
      in: query
      required: true
      x-ms-parameter-location: client
      schema:
        type: string
        default: 2022-02-01-preview
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'