API Support

Salesforce developers can also access timezone information by making calls to the Local Time API from Apex. Following are the available API methods.

1. tz.LocalTimeV2.getTimezones

Returns a JSON array containing a list of items of custom apex subclass type TimezoneResponse. For each item in the request, you will get a corresponding item in the response.

Signature

global static String tz.LocalTimeV2.getTimezones(String request)

Parameters

request
Type: A JSON array containing a list of items of custom apex subclass type TimezoneRequest.

Return Value

Type: String

Example

public class LocalTimeAPITest {

    // sub class to store the timezone request information
    public with sharing class TimezoneRequest {
        public String id; // record id or some unique key
        public String country;
        public String state;
        public String city;
        public String postalcode;
        public String phone;
        public Boolean adjust_dst; // set it to true if data needs to be adjusted for DST
        public Boolean broad_match; // set it to true if result does not need to be very clear-cut or definitive
    }

    // sub class to store timezone response
    public with sharing class TimezoneResponse {
        public String id; // record id or some unique key
        public Decimal offset;
        public Decimal dst_offset;
        public String abbreviation;
        public String dst_abbreviation;
        public String tz_name;
        public String dst_tz_name;
        public String tz_iana; // timezone by iana org
        public String tz_sfdc; // salesforce timezone
        public String dst_setting; // Id of the DST_Setting__c record
        public String system_country; // country name in the database
        public String system_state; // state name in the database
    }

    // Get the timezones for a given request
    // if the request is ambiguous, all available timezones are returned
    // if the request is unambiguous, exact timezone is returned
    public static void testgetTimezones() {
        List<TimezoneRequest> tz_reqs = new List<TimezoneRequest>();

        TimezoneRequest tz_req = new TimezoneRequest();
        tz_req.id = '100';
        tz_req.country = 'USA';
        tz_req.state = 'TX';
        tz_req.adjust_dst = true;
        tz_req.broad_match = true;
        tz_reqs.add(tz_req); // ambiguous and broad match is set to true, so we expect to get two records for this request as Texas observes two timezones

        tz_req = new TimezoneRequest();
        tz_req.id = '200';
        tz_req.country = 'USA';
        tz_req.state = 'TX';
        tz_req.adjust_dst = true;
        tz_reqs.add(tz_req); // ambiguous but broad match is false, so we expect to get one record with the widely used timezone in Texas

        tz_req = new TimezoneRequest();
        tz_req.id = '300';
        tz_req.country = 'USA';
        tz_req.state = 'TX';
        tz_req.postalcode = '79910';
        tz_req.adjust_dst = true;
        tz_reqs.add(tz_req); // unambiguous, so we expect to get one record for this request
        // it does not matter if you set broad_match to true or false

        tz_req = new TimezoneRequest();
        tz_req.id = '400';
        tz_req.country = 'Germany';
        tz_req.adjust_dst = false;
        tz_reqs.add(tz_req); // unambiguous, so we expect to get one record for this request
        // it does not matter if you set broad_match to true or false

        tz_req = new TimezoneRequest();
        tz_req.id = '500';
        tz_req.country = 'USA';
        tz_req.phone = '+1 212 1234'; // New York
        tz_req.adjust_dst = false;
        tz_reqs.add(tz_req); // unambiguous, so we expect to get one timezone record based on phone area code as New York observes one timezone

        tz_req = new TimezoneRequest();
        tz_req.id = '600';
        tz_req.country = 'USA';
        tz_req.state = 'CA';
        tz_req.adjust_dst = true;
        tz_reqs.add(tz_req); // unambiguous, so we expect to get one timezone record as California observes one timezone

        String request = JSON.serialize(tz_reqs);
        String resp = tz.LocalTimeV2.getTimezones(request); // make the API call

        Map<String, List<TimezoneResponse>> map_tzones = (Map<String, List<TimezoneResponse>>)JSON.deserialize(resp,Map<String, List<TimezoneResponse>>.class);

        List<TimezoneResponse> tzones = map_tzones.get('100');
        system.debug(tzones);
        // Expected response - two records
        /* (TimezoneResponse:[abbreviation=CDT, dst_abbreviation=null, dst_offset=null, dst_setting=a013N000002oBORQA2, dst_tz_name=null, id=100, offset=-5, system_country=USA, system_state=TX, tz_iana=America/Chicago, tz_name=Central Daylight Time, tz_sfdc=America/Chicago],
            TimezoneResponse:[abbreviation=MDT, dst_abbreviation=null, dst_offset=null, dst_setting=a013N000002oBORQA2, dst_tz_name=null, id=100, offset=-6, system_country=USA, system_state=TX, tz_iana=America/Denver, tz_name=Mountain Daylight Time, tz_sfdc=America/Denver])
        */

        tzones = map_tzones.get('200');
        system.debug(tzones);
        // Expected response - 1 record
        /* (TimezoneResponse:[abbreviation=CDT, dst_abbreviation=null, dst_offset=null, dst_setting=a013N000002oBORQA2, dst_tz_name=null, id=200, offset=-5, system_country=USA, system_state=TX, tz_iana=America/Chicago, tz_name=Central Daylight Time, tz_sfdc=America/Chicago])
        */

        tzones = map_tzones.get('300');
        system.debug(tzones);
        // Expected response - 1 record
        /* (TimezoneResponse:[abbreviation=MDT, dst_abbreviation=null, dst_offset=null, dst_setting=a013N000002oBORQA2, dst_tz_name=null, id=300, offset=-6, system_country=USA, system_state=TX, tz_iana=America/Denver, tz_name=Mountain Daylight Time, tz_sfdc=America/Denver])
        */

        tzones = map_tzones.get('400');
        system.debug(tzones);
        // Expected response - 1 record
        /* (TimezoneResponse:[abbreviation=CET, dst_abbreviation=CEST, dst_offset=2, dst_setting=a013N000002oBMIQA2, dst_tz_name=Central European Summer Time, id=400, offset=1, system_country=GERMANY, system_state=null, tz_iana=Europe/Berlin, tz_name=Central European Time, tz_sfdc=Europe/Berlin])
        */

        tzones = map_tzones.get('500');
        system.debug(tzones);
        // Expected response - 1 record
        /* (TimezoneResponse:[abbreviation=EST, dst_abbreviation=EDT, dst_offset=-4, dst_setting=a013N000002oBORQA2, dst_tz_name=Eastern Daylight Time, id=500, offset=-5, system_country=USA, system_state=null, tz_iana=America/New_York, tz_name=Eastern Standard Time, tz_sfdc=America/New_York])
        */

        tzones = map_tzones.get('600');
        system.debug(tzones);
        // Expected response - 1 record
        /* (TimezoneResponse:[abbreviation=PDT, dst_abbreviation=null, dst_offset=null, dst_setting=a013N000002oBORQA2, dst_tz_name=null, id=600, offset=-7, system_country=USA, system_state=CA, tz_iana=America/Los_Angeles, tz_name=Pacific Daylight Time, tz_sfdc=America/Los_Angeles])
        */

    }
} // class LocalTimeAPITest

2. tz.LocalTimeV2.getUTCOffset

Returns the UTC Offset of the specified datetime value in the specified time zone.

Signature

global static Decimal tz.LocalTimeV2.getUTCOffset(Datetime dt, String timeZoneIdString)

Parameters

dt
Type: Datetime

timeZoneIdString
Type: String
The time zone values should use only the values supported by Salesforce.

Return Value

Type: Decimal

Example

// Get the UTC Offset for a specific time zone like Europe/Berlin
Datetime dt = Datetime.newInstance(2022, 11, 7, 14, 0, 0); // Nov 07, 2022
system.debug(tz.LocalTimeV2.getUTCOffset(dt, 'Europe/Berlin')); // returns 1.0 as DST is off

dt = Datetime.newInstance(2023, 4, 5, 14, 0, 0); // April 05, 2023
system.debug(tz.LocalTimeV2.getUTCOffset(dt, 'Europe/Berlin')); // returns 2.0 as DST is on at this time

system.debug(tz.LocalTimeV2.getUTCOffset(dt, null)); // returns the offset based on the time zone of the running user who called the method.