swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector Geolocation API
schemes:
- https
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: '#/parameters/ClientId'
      - $ref: '#/parameters/SubscriptionKey'
      - $ref: '#/parameters/ApiVersion'
      - $ref: '#/parameters/JsonFormat'
      - name: ip
        in: query
        description: The IP address. Both IPv4 and IPv6 are allowed.
        required: true
        type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/IpAddressToLocationResult'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
      summary: Microsoft Azure Get Geolocation Ip Format
      tags:
      - Geolocation
definitions:
  ODataErrorResponse:
    type: object
    description: This response object is returned when an error occurs in the Azure Maps API.
    properties:
      error:
        $ref: '#/definitions/ODataError'
  IpAddressToLocationResult:
    description: This object is returned from a successful call to IP Address to country/region API
    type: object
    properties:
      countryRegion:
        $ref: '#/definitions/CountryRegion'
      ipAddress:
        description: The IP Address of the request.
        type: string
        readOnly: true
  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
  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: '#/definitions/ODataError'
      target:
        type: string
        readOnly: true
        description: If available, the target causing the error.
parameters:
  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.
    type: string
    in: header
    required: false
    x-ms-parameter-location: client
  JsonFormat:
    name: format
    description: Desired format of the response. Only `json` format is supported.
    type: string
    in: path
    required: true
    enum:
    - json
    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
  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.
    type: string
    in: query
    required: false
    x-ms-parameter-location: client
  ApiVersion:
    name: api-version
    description: Version number of Azure Maps API. Current version is 1.0
    type: string
    in: query
    required: true
    default: '1.0'
    x-ms-parameter-location: client
responses:
  '500':
    description: An error occurred while processing the request. Please try again later.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
  '404':
    description: 'Not Found: the requested resource could not be found, but it may be available again in the future.'
    schema:
      $ref: '#/definitions/ODataErrorResponse'
  '403':
    description: Permission, capacity, or authentication issues.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
  '400':
    description: 'Bad request: one or more parameters were incorrectly specified or are mutually exclusive.'
    schema:
      $ref: '#/definitions/ODataErrorResponse'
  '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.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
    headers:
      WWW-Authenticate:
        type: string
        description: Bearer realm="https://atlas.microsoft.com/", error="invalid_token", error_description="The access token expired"
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'