swagger: '2.0'
info:
  title: Microsoft Azure Azure Maps Time Zone Service
  version: '1.0'
  description: Azure Maps Time Zone REST APIs
host: atlas.microsoft.com
schemes:
  - https
consumes: []
produces:
  - application/json
  - application/xml
securityDefinitions:
  AADToken:
    type: oauth2
    authorizationUrl: https://login.microsoftonline.com/common/oauth2/authorize
    flow: implicit
    description: >-
      These are the [Microsoft Entra OAuth
      2.0](https://docs.microsoft.com/azure/active-directory/develop/v1-overview)
      Flows. When paired with [Azure role-based
      access](https://docs.microsoft.com/azure/role-based-access-control/overview)
      control it can be used to control access to Azure Maps REST APIs. Azure
      role-based access controls are used to designate access to one or more
      Azure Maps resource account or sub-resources. Any user, group, or service
      principal can be granted access via a  built-in role or a custom role
      composed of one or more permissions to Azure Maps REST APIs.


      To implement scenarios, we recommend viewing [authentication
      concepts](https://aka.ms/amauth). In summary, this security definition
      provides a solution for modeling application(s) via objects capable of
      access control on specific APIs and scopes.


      #### Notes

      * This security definition **requires** the use of the `x-ms-client-id`
      header to indicate which Azure Maps resource the application is requesting
      access to. This can be acquired from the [Maps management
      API](https://aka.ms/amauthdetails).

      * 

      The `Authorization URL` is specific to the Azure public cloud instance.
      Sovereign clouds have unique Authorization URLs and Microsoft Entra ID
      configurations. 

      * 

      The Azure role-based access control is configured from the [Azure
      management plane](https://aka.ms/amrbac) via Azure portal, PowerShell,
      CLI, Azure SDKs, or REST APIs.

      * 

      Usage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for
      configuration based setup of an application for multiple use cases.

      * For more information on Microsoft identity platform, see [Microsoft
      identity platform
      overview](https://learn.microsoft.com/entra/identity-platform/v2-overview).
    scopes:
      https://atlas.microsoft.com/.default: https://atlas.microsoft.com/.default
  SharedKey:
    type: apiKey
    description: >-
      This is a shared key that is provisioned when you [Create an Azure Maps
      account](https://docs.microsoft.com/azure/azure-maps/quick-demo-map-app#create-an-azure-maps-account)
      in the Azure portal or using PowerShell, CLI, Azure SDKs, or REST API.

       With this key, any application can access all REST API. In other words, this key can be used as a master key in the account that they are issued in.

       For publicly exposed applications, our recommendation is to use the [confidential client applications](https://docs.microsoft.com/azure/azure-maps/authentication-best-practices#confidential-client-applications) approach to access Azure Maps REST APIs so your key can be securely stored.
    name: subscription-key
    in: query
  SasToken:
    type: apiKey
    description: >-
      This is a shared access signature token is created from the List SAS
      operation on the [Azure Maps resource](https://aka.ms/amauth) through the
      Azure management plane via Azure portal, PowerShell, CLI, Azure SDKs, or
      REST APIs.

       With this token, any application is authorized to access with Azure role-based access controls and fine-grain control to the expiration, rate, and region(s) of use for the particular token. In other words, the SAS Token can be used to allow applications to control access in a more secured way than the shared key.

       For publicly exposed applications, our recommendation is to configure a specific list of allowed origins on the [Map account resource](https://aka.ms/amauth) to limit rendering abuse and regularly renew the SAS Token.
    name: SAS Token
    in: header
security:
  - AADToken:
      - https://atlas.microsoft.com/.default
  - SharedKey: []
  - SasToken: []
responses:
  '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"
  '403':
    description: Permission, capacity, or authentication issues.
    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'
  '500':
    description: An error occurred while processing the request. Please try again later.
    schema:
      $ref: '#/definitions/ODataErrorResponse'
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
  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
  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
  TimezoneAcceptLanguage:
    name: Accept-Language
    in: header
    description: >-
      Specifies the language code in which the timezone names should be
      returned. If no language code is provided, the response will be in "EN".
      Please refer to [Supported
      Languages](https://docs.microsoft.com/en-us/azure/azure-maps/supported-languages)
      for details.
    required: false
    type: string
    x-ms-parameter-location: method
  TimezoneOptions:
    name: options
    in: query
    description: >-
      Alternatively, use alias "o". Options available for types of information
      returned in the result.
    required: false
    type: string
    enum:
      - none
      - zoneInfo
      - transitions
      - all
    x-ms-enum:
      name: TimezoneOptions
      modelAsString: true
      values:
        - value: none
          description: Do not include zoneinfo or transitions in the result.
        - value: zoneInfo
          description: Include additional time zone info in the result.
        - value: transitions
          description: >-
            Include transition information in the result (The number of
            transitions is currently capped at 250).
        - value: all
          description: Include both zoneinfo and transitions in the result.
    x-ms-parameter-location: method
  TimezoneTimeStamp:
    name: timeStamp
    in: query
    description: >-
      Alternatively, use alias "stamp", or "s". Reference time, if omitted, the
      API will use the machine time serving the request.
    required: false
    type: string
    x-ms-parameter-location: method
    format: date-time
  TimezoneTransitionsFrom:
    name: transitionsFrom
    in: query
    description: >-
      Alternatively, use alias "tf". The start date from which daylight savings
      time (DST) transitions are requested, only applies when "options" = all or
      "options" = transitions.
    required: false
    type: string
    x-ms-parameter-location: method
    format: date-time
  TimezoneTransitionsYears:
    name: transitionsYears
    in: query
    description: >-
      Alternatively, use alias "ty". The number of years from "transitionsFrom"
      for which DST transitions are requested, only applies when "options" = all
      or "options" = transitions.
    required: false
    type: integer
    x-ms-parameter-location: method
paths:
  /timezone/byId/{format}:
    get:
      x-publish: true
      description: >-
        __Time Zone by Id__<br><br>**Applies to**: S0 and S1 pricing
        tiers.<br><br><br>This API returns current, historical, and future time
        zone information for the specified IANA time zone ID.
      operationId: microsoftAzureTimezoneGettimezonebyid
      x-ms-examples:
        GetTimezoneByID:
          $ref: ./examples/GetTimezoneByID.json
      parameters:
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/SubscriptionKey'
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/TimezoneAcceptLanguage'
        - $ref: '#/parameters/TimezoneOptions'
        - $ref: '#/parameters/TimezoneTimeStamp'
        - $ref: '#/parameters/TimezoneTransitionsFrom'
        - $ref: '#/parameters/TimezoneTransitionsYears'
        - $ref: '#/parameters/JsonFormat'
        - name: query
          in: query
          description: The IANA time zone ID.
          required: true
          type: string
          x-ms-parameter-location: method
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TimezoneByIdResult'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
      produces:
        - application/json
      summary: Microsoft Azure Get Timezone Byid Format
      tags:
        - Timezone
  /timezone/byCoordinates/{format}:
    get:
      x-publish: true
      description: >-
        __Time Zone by Coordinates__<br><br>**Applies to**: S0 and S1 pricing
        tiers.<br><br><br>This API returns current, historical, and future time
        zone information for a specified latitude-longitude pair. In addition,
        the API provides sunset and sunrise times for a given location.
      operationId: microsoftAzureTimezoneGettimezonebycoordinates
      x-ms-examples:
        GetTimezoneByCoordinates:
          $ref: ./examples/GetTimezoneByCoordinates.json
      parameters:
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/SubscriptionKey'
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/TimezoneAcceptLanguage'
        - $ref: '#/parameters/TimezoneOptions'
        - $ref: '#/parameters/TimezoneTimeStamp'
        - $ref: '#/parameters/TimezoneTransitionsFrom'
        - $ref: '#/parameters/TimezoneTransitionsYears'
        - $ref: '#/parameters/JsonFormat'
        - name: query
          in: query
          description: >-
            Coordinates of the point for which time zone information is
            requested. The applicable query is specified as a comma separated
            string composed by latitude followed by longitude e.g.
            "47.641268,-122.125679".
          required: true
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TimezoneByCoordinatesResult'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
      produces:
        - application/json
      summary: Microsoft Azure Get Timezone Bycoordinates Format
      tags:
        - Timezone
  /timezone/enumWindows/{format}:
    get:
      x-publish: true
      description: >-
        __Enumerate Windows Time Zones__<br><br><br>**Applies to**: S0 and S1
        pricing tiers.<br><br><br>This API returns a full list of Windows Time
        Zone IDs.
      operationId: microsoftAzureTimezoneGettimezoneenumwindows
      x-ms-examples:
        GetTimezoneEnumWindows:
          $ref: ./examples/GetTimezoneEnumWindows.json
      parameters:
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/SubscriptionKey'
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/JsonFormat'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TimezoneEnumWindowsResult'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
      produces:
        - application/json
      summary: Microsoft Azure Get Timezone Enumwindows Format
      tags:
        - Timezone
  /timezone/enumIana/{format}:
    get:
      x-publish: true
      description: >-
        __Enumerate IANA Time Zones__<br><br><br>**Applies to**: S0 and S1
        pricing tiers.<br><br><br>This API returns a full list of IANA time zone
        IDs. Updates to the IANA service will be reflected in the system within
        one day.
      operationId: microsoftAzureTimezoneGettimezoneenumiana
      x-ms-examples:
        GetTimezoneEnumIANA:
          $ref: ./examples/GetTimezoneEnumIANA.json
      parameters:
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/SubscriptionKey'
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/JsonFormat'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TimezoneEnumIanaResult'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
      produces:
        - application/json
      summary: Microsoft Azure Get Timezone Enumiana Format
      tags:
        - Timezone
  /timezone/ianaVersion/{format}:
    get:
      x-publish: true
      description: >-
        __Time Zone IANA Version__<br><br><br>**Applies to**: S0 and S1 pricing
        tiers.<br><br><br>This API returns the current IANA version number.
      operationId: microsoftAzureTimezoneGettimezoneianaversion
      x-ms-examples:
        GetTimezoneIANAVersion:
          $ref: ./examples/GetTimezoneIANAVersion.json
      parameters:
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/SubscriptionKey'
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/JsonFormat'
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TimezoneIanaVersionResult'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
      produces:
        - application/json
      summary: Microsoft Azure Get Timezone Ianaversion Format
      tags:
        - Timezone
  /timezone/windowsToIana/{format}:
    get:
      x-publish: true
      description: >-
        __Windows to IANA Time Zone__<br><br><br>**Applies to**: S0 and S1
        pricing tiers.<br><br><br>This API returns a corresponding IANA ID,
        given a valid Windows Time Zone ID. Multiple IANA IDs may be returned
        for a single Windows ID. It is possible to narrow these results by
        adding an optional territory parameter.
      operationId: microsoftAzureTimezoneGettimezonewindowstoiana
      x-ms-examples:
        GetTimezoneWindowsToIANA:
          $ref: ./examples/GetTimezoneWindowsToIANA.json
      parameters:
        - $ref: '#/parameters/ClientId'
        - $ref: '#/parameters/SubscriptionKey'
        - $ref: '#/parameters/ApiVersion'
        - $ref: '#/parameters/JsonFormat'
        - name: query
          in: query
          description: The Windows time zone ID.
          required: true
          type: string
        - name: territory
          in: query
          description: Windows Time Zone territory code.
          required: false
          type: string
      responses:
        '200':
          description: OK
          schema:
            $ref: '#/definitions/TimezoneWindowToIanaResult'
        '400':
          $ref: '#/responses/400'
        '401':
          $ref: '#/responses/401'
        '403':
          $ref: '#/responses/403'
        '404':
          $ref: '#/responses/404'
        '500':
          $ref: '#/responses/500'
      produces:
        - application/json
      summary: Microsoft Azure Get Timezone Windowstoiana Format
      tags:
        - Timezone
definitions:
  ODataErrorResponse:
    type: object
    description: >-
      This response object is returned when an error occurs in the Azure Maps
      API.
    properties:
      error:
        $ref: '#/definitions/ODataError'
  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.
  Country:
    type: object
    description: A country/region  record.
    properties:
      Name:
        description: country/region  Name
        type: string
        readOnly: true
      Code:
        description: ISO-3166 2-letter country/region  code for the country/region .
        type: string
        readOnly: true
  TimeTransition:
    type: object
    readOnly: true
    properties:
      Tag:
        description: Tag property
        type: string
        readOnly: true
      StandardOffset:
        description: StandardOffset property
        type: string
        readOnly: true
      DaylightSavings:
        description: DaylightSavings property
        type: string
        readOnly: true
      UtcStart:
        description: Start date, start time for this transition period
        type: string
        readOnly: true
        format: date-time
      UtcEnd:
        description: End date, end time for this transition period
        type: string
        readOnly: true
        format: date-time
  TimezoneByIdResult:
    description: This object is returned from a successful Timezone By ID call
    type: object
    properties:
      Version:
        description: Version property
        type: string
        readOnly: true
      ReferenceUtcTimestamp:
        description: Reference Utc Timestamp property
        type: string
        readOnly: true
        format: date-time
      TimeZones:
        $ref: '#/definitions/TimeZonesById'
  TimezoneByCoordinatesResult:
    description: This object is returned from a successful Timezone By Coordinates call
    type: object
    properties:
      Version:
        description: Version property
        type: string
        readOnly: true
      ReferenceUtcTimestamp:
        description: Reference Utc Timestamp property
        type: string
        readOnly: true
        format: date-time
      TimeZones:
        $ref: '#/definitions/TimeZonesByCoordinates'
  TimezoneEnumWindowsResult:
    description: This object is returned from a successful Timezone Enum Windows call
    type: array
    items:
      $ref: '#/definitions/TimezoneEnumWindow'
  TimezoneEnumWindow:
    type: object
    properties:
      WindowsId:
        description: Windows Id property
        type: string
        readOnly: true
      Territory:
        description: Territory property
        type: string
        readOnly: true
      IanaIds:
        description: IanaIds array
        type: array
        items:
          type: string
          readOnly: true
  TimezoneEnumIanaResult:
    description: This object is returned from a successful Timezone Enum IANA call
    type: array
    items:
      $ref: '#/definitions/IanaId'
  TimezoneIanaVersionResult:
    description: This object is returned from a successful Timezone IANA Version call
    type: object
    properties:
      version:
        description: Version property
        type: string
        readOnly: true
  TimezoneWindowToIanaResult:
    description: This object is returned from a successful Timezone Windows To IANA call
    type: array
    items:
      $ref: '#/definitions/IanaId'
  IanaId:
    type: object
    properties:
      id:
        description: Id property
        type: string
        readOnly: true
      isAlias:
        description: IsAlias property
        type: boolean
        readOnly: true
      aliasOf:
        description: AliasOf property
        type: string
        readOnly: true
      hasZone1970Location:
        description: HasZone1970Location property
        type: boolean
        readOnly: true
  TimeZonesById:
    description: TimeZoneById array
    type: array
    readOnly: true
    items:
      $ref: '#/definitions/TimezoneById'
  TimeZonesByCoordinates:
    description: TimeZoneByCoordinates array
    type: array
    readOnly: true
    items:
      $ref: '#/definitions/TimeZoneByCoordinates'
  TimezoneById:
    type: object
    properties:
      Id:
        description: Id property
        type: string
        readOnly: true
      Aliases:
        description: >-
          An array of time zone ID aliases. Only returned when
          [options]=*zoneinfo* or *all*.


          Note: may be null.
        type: array
        readOnly: true
        items:
          type: string
          readOnly: true
      Countries:
        description: >-
          An array of country/region records. Only returned when
          [options]=*zoneinfo* or *all*.
        type: array
        readOnly: true
        items:
          $ref: '#/definitions/Country'
      Names:
        $ref: '#/definitions/Names'
      ReferenceTime:
        $ref: '#/definitions/ReferenceTimeById'
      RepresentativePoint:
        $ref: '#/definitions/RepresentativePoint'
      TimeTransitions:
        description: >-
          Time zone DST transitions from [transitionsFrom] until timestamp + 1
          year.
        type: array
        readOnly: true
        items:
          $ref: '#/definitions/TimeTransition'
  TimeZoneByCoordinates:
    type: object
    properties:
      Id:
        description: Id property
        type: string
        readOnly: true
      Aliases:
        description: >-
          An array of time zone ID aliases.  Only returned when
          [options]=*zoneinfo* or *all*.


          Note: may be null.
        type: array
        readOnly: true
        items:
          type: string
          readOnly: true
      Countries:
        description: >-
          An array of country/region records. Only returned when
          [options]=*zoneinfo* or *all*.
        type: array
        readOnly: true
        items:
          $ref: '#/definitions/Country'
      Names:
        $ref: '#/definitions/Names'
      ReferenceTime:
        $ref: '#/definitions/ReferenceTimeByCoordinates'
      RepresentativePoint:
        $ref: '#/definitions/RepresentativePoint'
      TimeTransitions:
        description: >-
          Time zone DST transitions from [transitionsFrom] until timestamp + 1
          year.
        type: array
        readOnly: true
        items:
          $ref: '#/definitions/TimeTransition'
  Names:
    type: object
    description: Timezone names object.
    properties:
      ISO6391LanguageCode:
        description: The ISO 639-1 language code of the Names
        type: string
        readOnly: true
      Generic:
        description: Generic Name
        type: string
        readOnly: true
      Standard:
        description: Standard Name
        type: string
        readOnly: true
      Daylight:
        description: Daylight Name
        type: string
        readOnly: true
  ReferenceTimeById:
    description: Details in effect at the local time.
    type: object
    readOnly: true
    properties:
      Tag:
        description: >-
          Time zone name in effect at the reference timestamp (i.e. PST or PDT
          depending whether Daylight Savings Time is in effect).
        type: string
        readOnly: true
      StandardOffset:
        description: UTC offset in effect at the `ReferenceUTCTimestamp`.
        type: string
        readOnly: true
      DaylightSavings:
        description: Time saving in minutes in effect at the `ReferenceUTCTimestamp`.
        type: string
        readOnly: true
      WallTime:
        description: >-
          Current wall time at the given time zone as shown in the `Tag`
          property.
        type: string
        readOnly: true
      PosixTzValidYear:
        description: >-
          The year this POSIX string is valid for. Note: A POSIX string will
          only be valid in the given year.
        type: integer
        readOnly: true
      PosixTz:
        description: POSIX string used to set the time zone environment variable.
        type: string
        readOnly: true
  ReferenceTimeByCoordinates:
    description: Details in effect at the local time.
    type: object
    readOnly: true
    properties:
      Tag:
        description: >-
          Time zone name in effect at the reference timestamp (i.e. PST or PDT
          depending whether Daylight Savings Time is in effect).
        type: string
        readOnly: true
      StandardOffset:
        description: UTC offset in effect at the `ReferenceUTCTimestamp`.
        type: string
        readOnly: true
      DaylightSavings:
        description: Time saving in minutes in effect at the `ReferenceUTCTimestamp`.
        type: string
        readOnly: true
      WallTime:
        description: >-
          Current wall time at the given time zone as shown in the `Tag`
          property.
        type: string
        readOnly: true
      PosixTzValidYear:
        description: >-
          The year this POSIX string is valid for. Note: A POSIX string will
          only be valid in the given year.
        type: integer
        readOnly: true
      PosixTz:
        description: POSIX string used to set the time zone environment variable.
        type: string
        readOnly: true
      Sunrise:
        description: Sunrise at the given time zone as shown in the `Tag` property.
        type: string
        readOnly: true
      Sunset:
        description: Sunset at the given time zone as shown in the `Tag` property.
        type: string
        readOnly: true
  RepresentativePoint:
    description: Representative point property
    type: object
    readOnly: true
    properties:
      Latitude:
        description: Latitude property
        type: number
        readOnly: true
      Longitude:
        description: Longitude property
        type: number
        readOnly: true
tags:
  - name: Timezone