List Time Zones

  • Article

The list operation retrieves all available time zone data for either the IANA or Windows time zone standard. Additionally, information about any particular time zone can be retrieved using the ID for that time zone formatted in either the IANA or Windows time zone standard.

API Templates

Note

These templates support both HTTP and HTTPS.

Get a Full List of Time zones for a Given Standard (Windows or IANA)

The Time Zone API list operation returns a complete list of time zone information for either the Microsoft Windows or IANA Time Zone standard. In the request URL specify timezonestandard = WINDOWS or timezonestandard = IANA to retrieve a list of Windows or IANA Time Zone information, respectively.

https://dev.virtualearth.net/REST/v1/TimeZone/List/?timezonestandard={IANA_or_Windows}&key={BingMapsKey}

Time Zone from Time Zone ID (Windows or IANA)

Given a specified Time Zone ID in either the Microsoft Windows or IANA Time Zone format, e.g. desttz = America/los_angeles, the Time Zone API returns information about that time zone.

https://dev.virtualearth.net/REST/v1/TimeZone/?desttz={time_zone_id}&key={BingMapsKey}

API Parameters

Parameters Alias Descriptions Values
desttz Required for getting Time Zone by Local Time Zone ID. The ID of the destination time zone. Any valid IANA or Windows time zone ID.

Examples:

- Americas/LosAngeles
- Cape Verde Standard Time
includeDstRules Optional. If set to true then DST rule information will be returned in the response.

Note: For information about DST rules, see the DSTRule Resource.		 Either true or false.

Default: false
timezonestandard tzstd Required for using the List operation. Name of the time zone standard. One of the following values must be specified:

- IANA
- Windows
output o Optional. Output format of the response. Format of the response:

- JSON
- XML

Default: JSON

Note

The Time Zone API does not maintain historical record of any time zone or day light settings. If a location had a different time zone in the past, it is not considered. The Bing Maps Time Zone API results are based only on current policies and standards.

Response

Detailed information about Time Zone API responses can be found at Time Zone Data.

Successful calls to Time Zone API with the ist operation return a list of TimeZone Resources with complete information about either the IANA or Microsoft Windows Time Zone standard.

If applicable, daylight savings information is included separately in the ConvertedTime Resource and DSTRule Resource fields of the response.

Time Zone API responses are available in JSON and XML formats.

Examples

Return a List of Timezones for a Given Standard

The List operation for the Time Zone API returns the complete list of either IANA or Windows Time Zone IDs by setting the timezonestandard parameter to either iana or windows, respectively.

The following URL request returns a list of the Windows Time Zone IDs:

https://dev.virtualearth.net/REST/V1/TimeZone/List/?timezonestandard=windows&key={BingMapsKey}

The (truncated) JSON response:

{
    "authenticationResultCode": "ValidCredentials",
    "brandLogoUri": "http://dev.virtualearth.net/Branding/logo_powered_by.png",
    "copyright": "Copyright © 2018 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.",
    "resourceSets": [
        {
            "estimatedTotal": 128,
            "resources": [
                {
                    "__type": "RESTTimeZone:http://schemas.microsoft.com/search/local/ws/rest/v1",
                    "timeZone": {
                        "genericName": "UTC-11",
                        "ianaTimeZoneId": "Pacific/Niue",
                        "windowsTimeZoneId": "UTC-11",
                        "utcOffset": "-11:00"
                    }
                },
                
                /*  The other 127 resources removed for brevity  */
         }
    ],
    "statusCode": 200,
    "statusDescription": "OK",
    "traceId": "fa78920f38d24d0490a8b05300c6aab6|TW-CWU-178|7.7.0.0"
}

Return Details about a Particular Timezone

The Time Zone API can be used to retrieve information about any timezone by specifying either its IANA or Windows Time Zone ID.

In this example, to get information about the time zone in L.A., we set desttz to the IANA code America/Los_Angeles.

https://dev.virtualearth.net/REST/V1/TimeZone/?desttz=America/Los_Angeles&includeDstRules=true&key={BingMapsKey}

The JSON response for the Los Angeles time zone:

{
    "authenticationResultCode": "ValidCredentials",
    "brandLogoUri": "http://dev.virtualearth.net/Branding/logo_powered_by.png",
    "copyright": "Copyright © 2018 Microsoft and its suppliers. All rights reserved. This API cannot be accessed and the content and any results may not be used, reproduced or transmitted in any manner without express written permission from Microsoft Corporation.",
    "resourceSets": [
        {
            "estimatedTotal": 1,
            "resources": [
                {
                    "__type": "RESTTimeZone:http://schemas.microsoft.com/search/local/ws/rest/v1",
                    "timeZone": {
                        "genericName": "Pacific Standard Time",
                        "abbreviation": "PST",
                        "ianaTimeZoneId": "America/Los_Angeles",
                        "windowsTimeZoneId": "Pacific Standard Time",
                        "utcOffset": "-8:00",
                        "convertedTime": {
                            "localTime": "2018-08-06T14:46:55",
                            "utcOffsetWithDst": "-7:00",
                            "timeZoneDisplayName": "Pacific Daylight Time",
                            "timeZoneDisplayAbbr": "PDT"
                        },
                        "dstRule": {
                            "dstStartMonth": "Mar",
                            "dstStartDateRule": "Sun>=8",
                            "dstStartTime": "2:00",
                            "dstAdjust1": "1:00",
                            "dstEndMonth": "Nov",
                            "dstEndDateRule": "Sun>=1",
                            "dstEndTime ": "2:00",
                            "dstAdjust2": "0"
                        }
                    }
                }
            ]
        }
    ],
    "statusCode": 200,
    "statusDescription": "OK",
    "traceId": "7d925d7df36f4b3383ebc63ddba8e91d|TW-CWU-178|7.7.0.0"
}

HTTP Status Codes

Note

For more about these HTTP codes, see Status Codes and Error Handling.

When the request is successful, the following HTTP status code is returned.

  • 200

When the request is not successful, the response returns one of the following errors.

  • 400
  • 500