Microsoft Azure Geolocation API

openapi: 3.2.0
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Geolocation API
tags:
- name: Geolocation
paths:
  /geolocation/ip/{format}:
    get:
      x-publish: true
      description: '<br>**Applies to**: S0 and S1 pricing tiers.<br><br><br>This service will return the ISO country code for the provided IP address. Developers can use this information to block or alter certain content based on geographical locations where the application is being viewed from.'
      operationId: microsoftAzureGeolocationGetiptolocation
      x-ms-examples:
        GetLocationByIpAddress:
          $ref: ./examples/GetLocationByIpAddress.json
      parameters:
      - $ref: '#/components/parameters/ClientId'
      - $ref: '#/components/parameters/SubscriptionKey'
      - $ref: '#/components/parameters/ApiVersion'
      - $ref: '#/components/parameters/JsonFormat'
      - name: ip
        in: query
        description: The IP address. Both IPv4 and IPv6 are allowed.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IpAddressToLocationResult'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      summary: Microsoft Azure Get Geolocation Ip Format
      tags:
      - Geolocation
components:
  responses:
    '401':
      description: Access denied due to invalid subscription key or invalid Microsoft Entra ID bearer token.  Make sure to provide a valid key for an active Azure subscription and Maps resource.  Otherwise, verify the [WWW-Authenticate](https://tools.ietf.org/html/rfc6750#section-3.1) header for error code and description of the provided Microsoft Entra ID bearer token.
      headers:
        WWW-Authenticate:
          description: Bearer realm="https://atlas.microsoft.com/", error="invalid_token", error_description="The access token expired"
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataErrorResponse'
    '400':
      description: 'Bad request: one or more parameters were incorrectly specified or are mutually exclusive.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataErrorResponse'
    '500':
      description: An error occurred while processing the request. Please try again later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataErrorResponse'
    '403':
      description: Permission, capacity, or authentication issues.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataErrorResponse'
    '404':
      description: 'Not Found: the requested resource could not be found, but it may be available again in the future.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ODataErrorResponse'
  parameters:
    JsonFormat:
      name: format
      description: Desired format of the response. Only `json` format is supported.
      in: path
      required: true
      x-ms-enum:
        name: JsonFormat
        modelAsString: true
        values:
        - value: json
          description: '[The JavaScript Object Notation Data Interchange Format](https://tools.ietf.org/html/rfc8259)'
      x-ms-parameter-location: method
      schema:
        type: string
        enum:
        - json
    SubscriptionKey:
      name: subscription-key
      description: One of the Azure Maps keys provided from an Azure Map Account. Please refer to this [article](https://docs.microsoft.com/azure/azure-maps/how-to-manage-authentication) for details on how to manage authentication.
      in: query
      required: false
      x-ms-parameter-location: client
      schema:
        type: string
    ClientId:
      name: x-ms-client-id
      description: Specifies which account is intended for usage in conjunction with the Microsoft Entra ID security model.  It represents a unique ID for the Azure Maps account and can be retrieved from the Azure Maps management  plane Account API. To use Microsoft Entra ID security in Azure Maps see the following [articles](https://aka.ms/amauthdetails) for guidance.
      in: header
      required: false
      x-ms-parameter-location: client
      schema:
        type: string
    ApiVersion:
      name: api-version
      description: Version number of Azure Maps API. Current version is 1.0
      in: query
      required: true
      x-ms-parameter-location: client
      schema:
        type: string
        default: '1.0'
  schemas:
    ODataError:
      type: object
      description: This object is returned when an error occurs in the Azure Maps API.
      properties:
        code:
          type: string
          readOnly: true
          description: The ODataError code.
        message:
          type: string
          readOnly: true
          description: If available, a human-readable description of the error.
        details:
          type: array
          items:
            $ref: '#/components/schemas/ODataError'
        target:
          type: string
          readOnly: true
          description: If available, the target causing the error.
    CountryRegion:
      description: The object containing the country/region information.
      type: object
      readOnly: true
      properties:
        isoCode:
          description: The IP Address's 2-character code [(ISO 3166-1)](https://www.iso.org/iso-3166-country-codes.html) of the country or region. Please note, IP address in ranges reserved for special purpose will return Null for country/region.
          type: string
          readOnly: true
    IpAddressToLocationResult:
      description: This object is returned from a successful call to IP Address to country/region API
      type: object
      properties:
        countryRegion:
          $ref: '#/components/schemas/CountryRegion'
        ipAddress:
          description: The IP Address of the request.
          type: string
          readOnly: true
    ODataErrorResponse:
      type: object
      description: This response object is returned when an error occurs in the Azure Maps API.
      properties:
        error:
          $ref: '#/components/schemas/ODataError'
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/components/parameters/Endpoint'