Last Updated on July 14, 2023 by Rakesh Gupta

Big Idea or Enduring Question:

• How can you leverage Google’s Time Zone API to automatically update a lead’s time zone information based on their geo-coordinates?

Objectives:

After reading this blog, you’ll be able to:

Business Use case

What is Google’s Time Zone API?

Chances are high that your customer base is spread across multiple time zones. This factor can greatly influence your interactions with them, especially when scheduling calls, meetings, or sending out automated messages. The Salesforce platform offers a highly adaptable environment to store and manage customer data, but by default, it doesn’t provide a way to automatically record the timezone of the lead based on their geographic coordinates.

Google’s Time Zone API is a service offered by Google as part of its Google Maps platform. The API provides time zone data for any location worldwide based on latitude and longitude coordinates. This service can be particularly useful for developers who need to adjust communication according to a lead’s or contact’s geographical location or for businesses operating across different time zones.

The Time Zone API provides the following information:

• The time zone’s ID, as defined by the IANA Time Zone Database (for example, America/New_York).
• The time zone’s name (for example, Eastern Daylight Time).
• The time offset from Coordinated Universal Time (UTC) without considering Daylight Saving Time (rawOffset).
• The time offset due to Daylight Saving Time (dstOffset).

Note that the Google Time Zone API is subject to charges, so it’s important to understand the cost implications before implementing it.

How Google’s Time Zone API Works?

Google’s Time Zone API works by taking latitude and longitude coordinates and returning time zone data in JSON format. Here is a basic example of how to use it.

The following HTTP GET request gets time zone information for a location at latitude 40.712776 and longitude -74.005974 (New York City), and assumes you are making the request at a certain timestamp (UNIX timestamp).

https://maps.googleapis.com/maps/api/timezone/json?location=40.712776,-74.005974&timestamp=1458000000&key=YOUR_API_KEY

In the request URL above, replace YOUR_API_KEY with your actual API key.

Here is a sample response in JSON format that the API might return:

{
   "dstOffset" : 3600,
   "rawOffset" : -18000,
   "status" : "OK",
   "timeZoneId" : "America/New_York",
   "timeZoneName" : "Eastern Daylight Time"
}

The response includes the following information:

1. dstOffset: The offset for daylight-savings time in seconds. This will be zero if the time zone is not in daylight-savings time during the specified timestamp.
2. rawOffset: The offset from UTC (not counting daylight savings time) in seconds.
3. status: A string indicating the status of the request. “OK” means that the request was successful.
4. timeZoneId: A string containing the “tz” ID of the time zone (e.g., “America/New_York”).
5. timeZoneName: A string containing the long form name of the time zone (e.g., “Eastern Daylight Time”).

Remember, in the request URL, the timestamp parameter is required, and the location parameter expects latitude and longitude coordinates.

1. Timestamp: The desired time as seconds since midnight, January 1, 1970 UTC. The Time Zone API uses the timestamp to determine whether or not Daylight Savings should be applied based on the location’s time zone.
2. Location: A comma-separated latitude, longitude tuple, location=40.712776,-74.005974, representing the location to look up.

Also, don’t forget to include your API key.

Benefits of Using Google’s Time Zone API

Step 3.2: Formula to Calculate Timestamp

1. Under Toolbox, select Manager, then click New Resource to calculate the seconds since the Unix epoch (January 1, 1970, 00:00:00).
   
2. Input the following information:
   1. Resource Type: Formula
   2. API Name: forN_Timestamp
      
   3. Data Type: Number
   4. Decimal Places: 0
   5. Formula: ROUND((NOW() – DATETIMEVALUE(“1970-01-01 00:00:00”)) * 24 * 60 * 60, 0)
3. Click Done.

Step 3.3: Configure an HTTP GET Callout Action

HTTP Callout guides you through entering the details about the HTTP web-based service or REST API endpoint that you’re connecting to. After you complete the configuration, you invoke the action in a flow.

1. Under Run Asynchronously node, select Action.
2. Click + Create HTTP Callout.
3. Configure the external service that connects Salesforce to the HTTP-based API.
   1. Enter a Name for the external service.
   2. Select the named credential that you created in the step 2.
      
   3. Click Next.
4. The next step is to configure the invocable action that you can use in Flow Builder or across Salesforce.
   1. For Label, enter the action that the callout performs.
   2. Method: GET
   3. Add the URL endpoint for the request.
      1. URL Path: /maps/api/timezone/json
   4. Add query parameter keys if the API you’re calling has them. When you use this action in a flow, you input values for the defined keys.
      1. Click Add Key
         1. Key: location
         2. Data Type: String
         3. Required: True
      2. Click Add Key
         1. Key: timstamp
            
         2. Data Type: Integer
            
         3. Required: True
            
      3. Click Add Key
         1. Key: key
         2. Data Type: String
            
         3. Required: True
5. Provide a sample API response body. Salesforce generates a data structure from the sample response.
   1. Navigate to Provide Sample Response section.
   2. Click New.
   3. Paste a sample JSON response.
      Copy Code Copied Use a different Browser

      
      {
          "timeZoneName": "sample string",
          "rawOffset": 1,
          "timeZoneId": "sample string",
          "errorMessage": "sample string",
          "dstOffset": 1,
          "status": "sample string"
      }
      

   4. Click Review and confirm that the Apex data structure is correct.
   5. To make changes, edit the text in Sample JSON Response or select data types from the data structure.
   6. Click Review.
   7. Click Done.
6. Click Save.
7. Flow Builder creates the action and external service. The action is available in the Actions window in the flow.
8. The next step is to add apex action generated by HTTP Callout setup in the previous steps. We will use the Action element.
   1. Label the new action OpenWeather Callout.

   2. Set Input Values

      1. key: YOUR_OpenWeather_API_KEY
      2. location: {!$Record.Current_Position__Latitude__s},{!$Record.Current_Position__Longitude__s}
      3. timestamp: {!forN_Timestamp}
9. Click Done.

Step 3.4: Using Decision Element to Check the Time Zone API Callout Response Code

Now we will use the Decision element to check the Time Zone API response code.

1. On Flow Designer, click on the +icon and select the Decision element.
2. Enter a name in the Label field; the API Name will auto-populate.
3. Under Outcome Details, enter the Label the API Name will auto-populate.
4. Condition Requirements to Execute Outcome: All Conditions Are Met (AND)
   1. Row 1:
      1. Resource: {!Timezone_Callout.2XX.status}
      2. Operator: Equals
         
      3. Value: OK
   2. Add a new OUTCOME ORDER by clicking on the + icon to check Contact Provider response.
   3. Condition Requirements to Execute Outcome: Any Conditions Is Met (OR)
      1. Row 1:
         1. Resource: {!Timezone_Callout.2XX.status}
            
         2. Operator: Equals
         3. Value: INVALID_REQUEST
            
      2. Row 2:
         1. Resource: {!Timezone_Callout.2XX.status}
            
         2. Operator: Equals
         3. Value: OVER_DAILY_LIMIT
            
      3. Row 3:
         1. Resource: {!Timezone_Callout.2XX.status}
            
         2. Operator: Equals
         3. Value: OVER_QUERY_LIMIT
            
      4. Row 4:
         1. Resource: {!Timezone_Callout.2XX.status}
            
         2. Operator: Equals
         3. Value: REQUEST_DENIED
      5. Row 5:
         1. Resource: {!Timezone_Callout.2XX.status}
            
         2. Operator: Equals
         3. Value: UNKNOWN_ERROR
            
      6. Row 6:
         1. Resource: {!Timezone_Callout.2XX.status}
            
         2. Operator: Equals
         3. Value: ZERO_RESULTS
5. Click Done.

Step 3.5: Adding an Update Records Element to Update the Lead

The next step is to update the lead’s fields to store the callout response. We will use the Update Records element. 

1. On Flow Designer, below the Successful node, click on the +icon and select the Update Records element.
2. Enter a name in the Label field; the API Name will auto-populate.
3. For How to Find Records to Update and Set Their Values select Use the account record that triggered the flow
4. Set Filter Conditions: None – Always Update Record
5. Set Field Values for the Lead Records
   1. Row 1:
      1. Field: Time_Zone_Id__c
         
      2. Value: {!Timezone_Callout.2XX.timeZoneId}
         
   2. Click Add Field
   3. Row 2:
      1. Field: Time_Zone_Name__c
         
      2. Value: {!Timezone_Callout.2XX.timeZoneName}
         
   4. Click Add Field
   5. Row 3:
      1. Field: dstOffset__c
         
      2. Value: {!Timezone_Callout.2XX.dstOffset}
         
   6. Click Add Field
   7. Row 4:
      1. Field: rawOffset__c
         
      2. Value: {!Timezone_Callout.2XX.rawOffset}
6. Click Done.

Step 3.6: Add Action – Create a Record to Handle Error Response

The next step is to create a task, for this, we will use the Create Records element.

1. On Flow Designer, below the Failed node, click on the +icon and select the Create Records element.
2. Enter a name in the Label field; the API Name will auto-populate.
3. Input the following information:
   1. Enter Label the API Name will auto-populate.
   2. How Many Records to Create: One
   3. How to Set the Record Fields: Use separate resources, and literal values
   4. Object: Task
   5. Set Field Values for the Case
   6. Row 1:
      1. Field: Description
      2. Value: {!Timezone_Callout.2XX.status}
         
   7. Click Add Field
   8. Row 2:
      1. Field: OwnerId
      2. Value: {!$Record.OwnerId}
         
   9. Click Add Field
   10. Row 3:
       1. Field: Priority
       2. Value: High
   11. Click Add Field
   12. Row 4:
       1. Field: Status
       2. Value: Not Started
          
   13. Click Add Field
   14. Row 5:
       1. Field: Subject
       2. Value: {!Timezone_Callout.responseCode}
          
   15. Click Add Field
   16. Row 6:
       1. Field: WhatId
       2. Value: {!$Record.Id}
4. Click Done.

In the end, Jestilla’s Flow will look like the following screenshot:

Once everything looks good, perform the steps below: 

1. Click Save.
2. Enter Flow Label the API Name will auto-populate.
3. Click Show Advanced.
4. API Version for Running the Flow: 58
5. Interview Label: Get Timezone Info {!$Flow.CurrentDateTime}
6. Click Save.

Almost there! Once everything looks good, click the Activate button.

👉 Check out the video for step-by-step instructions.

Proof of Concept

Formative Assessment:

I want to hear from you!

What is one thing you learned from this post? How do you envision applying this new knowledge in the real world? Feel free to share in the comments below.