Share via

Convert Time Zone

  • Article

Note

Bing Maps Convert Time Zone API retirement

Bing Maps Convert Time Zone API is deprecated and will be retired. Free (Basic) account customers can continue to use Bing Maps Convert Time Zone API until June 30th, 2025. Enterprise account customers can continue to use Bing Maps Convert Time Zone API until June 30th, 2028. To avoid service disruptions, all implementations using Bing Maps Convert Time Zone API will need to be updated to use Azure Maps Timezone API by the retirement date that applies to your Bing Maps for Enterprise account type.

Azure Maps is Microsoft's next-generation maps and geospatial services for developers. Azure Maps has many of the same features as Bing Maps for Enterprise, and more. To get started with Azure Maps, create a free Azure subscription and an Azure Maps account. For more information about azure Maps, see Azure Maps Documentation. For migration guidance, see Bing Maps Migration Overview.

The Bing Maps Time Zone API performs time zone conversions. Given any datetime value in UTC format and the desired time zone, the API will return a response with that datetime converted to the specified time zone. If a date is provided in the UTC time stamp, the API will return the specified time zone with the proper DST values.

API Template

Note

This template supports both HTTP and HTTPS.

Convert UTC Datetime to a Different Time Zone

Converts a datetime value in UTC format to local time in the specified time zone. The date component is used to determine the correct day light saving settings.

https://dev.virtualearth.net/REST/v1/TimeZone/Convert/?datetime={datetime_utc}&desttz={timezoneid}&key={BingMapsKey}

API Parameters

Parameters Alias Descriptions Values
dateTime dt Required. The UTC date time string for the specified location. The date must be specified to apply the correct DST. The date time string must be in UTC format. If the date is not included, the returned time zone information may be incorrect.

Example: 2018-05-15T13:14:15Z
desttz Required. The ID of the destination time zone.

The value of datetime will be converted to the local time of this time zone.		 Any valid IANA or Windows time zone name.

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
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.

All successful requests return a TimeZone Resource.

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

Convert an UTC Date Time Stamp to a Different Time Zone

This example sends a request with a datetime stamp (e.g. 2018-05-15T13:14:15Z) and the desired time zone for Los Angeles (timezone = America/Los_Angeles) and returns an XML response.

Notice that there are two separate XML fields containing the DST information. The ConvertedTime field contains information about the local time zone at that location, including the UTC offset. The field DSTRule includes information about the DST start and ending times for that location.

The URL request:

https://dev.virtualearth.net/REST/v1/timezone/convert/?datetime=2018-05-15T13:14:15Z&desttz=america/Los_Angeles&o=xml&includeDstRules=true&key={BingMapsKey}

XML response:

<?xml version="1.0" encoding="ISO-8859-1"?>
<Response xmlns="http://schemas.microsoft.com/search/local/ws/rest/v1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <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.</Copyright>
    <BrandLogoUri>http://dev.virtualearth.net/Branding/logo_powered_by.png</BrandLogoUri>
    <StatusCode>200</StatusCode>
    <StatusDescription>OK</StatusDescription>
    <AuthenticationResultCode>ValidCredentials</AuthenticationResultCode>
    <TraceId>aa6dd02248ec48ed86fa981bd797ebae|TW-CWU-178|7.7.0.0</TraceId>
    <ResourceSets>
        <ResourceSet>
            <EstimatedTotal>1</EstimatedTotal>
            <Resources>
                <Resource xsi:type="RESTTimeZone">
                    <TimeZone>
                        <GenericName>Pacific Standard Time</GenericName>
                        <Abbreviation>PST</Abbreviation>
                        <IANATimeZoneId>America/Los_Angeles</IANATimeZoneId>
                        <WindowsTimeZoneId>Pacific Standard Time</WindowsTimeZoneId>
                        <UTCOffset>-8:00</UTCOffset>
                        <ConvertedTime>
                            <LocalTime>2018-05-15T06:14:15</LocalTime>
                            <UTCOffsetWithDst>-7:00</UTCOffsetWithDst>
                            <TimeZoneDisplayName>Pacific Daylight Time</TimeZoneDisplayName>
                            <TimeZoneDisplayAbbr>PDT</TimeZoneDisplayAbbr>
                        </ConvertedTime>
                        <DSTRule>
                            <DSTStartMonth>Mar</DSTStartMonth>
                            <DSTStartDateRule>Sun>=8</DSTStartDateRule>
                            <DSTStartTime>2:00</DSTStartTime>
                            <DSTAdjust1>1:00</DstAdjust1>
                            <DSTEndMonth>Nov</DSTEndMonth>
                            <DSTEndDateRule>Sun>=1</DSTEndDateRule>
                            <DSTEndTime>2:00</DSTEndTime>
                            <DSTAdjust2>0</DSTAdjust2>
                        </DSTRule>
                    </TimeZone>
                </Resource>
            </Resources>
        </ResourceSet>
    </ResourceSets>
</Response>

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