Time Zone HTTP Response - Precisely Data Integrity Suite

Data Integrity Suite APIs

Product

Data_Integrity

Spatial_Analytics

Data_Enrichment

geo_addressing_1

Services

Spatial Analytics

Data Enrichment

Geo Addressing

ft:title

Data Integrity Suite APIs

ft:locale

en-US

PublicationType

pt_developer

copyrightfirst

2023

copyrightlast

2026

Within the Timezone REST API, a request to the Timezone Service returns a list of results. Not every field will be returned with a result.

Below are the Response fields returned:

Table 1.
Field	Type	Description
errorMessage	String	Error message: The error message returnedfrom the service with an error code.
status	Status	Statusof the response.
timezones	<Result array>	Listof timezones based on the specified criteria.

Timezone AddressAPI 200 OK Examples:

Below is an example response for MatchedAddresses:

{
  "responses": [
    {
      "id": "1",
      "status": "OK",
      "timezone": {
        "timezoneName": "Mountain Time (MST/MDT)",
        "zoneType": "America/Denver",
        "utcOffset": -25200000,
        "dstOffset": 3600000,
        "timestamp": 1691138974831,
        "matchedAddress": {
          "formattedAddress": "950 JOSEPHINE ST, DENVER CO 80206-3728, United States",
          "formattedLocationAddress": "DENVER, CO  80206-3728",
          "admin1": "CO",
          "admin2": "DENVER COUNTY",
          "city": "DENVER",
          "street": "JOSEPHINE",
          "country": "USA",
          "postalCode": "80206",
          "postalCodeExt": "3728"
        }
      }
    }
  ]
}

Timezone Location API 200 OK Examples:

{
  "responses": [
    {
      "id": "1",
      "status": "OK",
      "timezone": {
        "timezoneName": "Central Time (CST/CDT)",
        "zoneType": "America/Chicago",
        "utcOffset": -21600000,
        "dstOffset": 3600000,
        "timestamp": 1691138974831
      }
    }
  ]
}

Timezone ServiceAPI Non 200 respose Schema

Status: 206 (Partial Response)
{
  "responses": [
    {
      "id": "1",
      "status": "OK",
      "timezone": {
        "timezoneName": "Central Time (CST/CDT)",
        "zoneType": "America/Chicago",
        "utcOffset": -21600000,
        "dstOffset": 3600000,
        "timestamp": 1691138974831
      }
    },
    {
      "id": "2",
      "status": "INVALID_REQUEST",
      "errorMessage": "Longitude is invalid (DIS-TZ-1006)"
    }
  ]
}

Status: 400 (Invalid Request):

{
  "errors": [
    {
      "status": "INVALID_REQUEST",
      "errorMessage": "Not able to identify abc country (DIS-TZ-1011)"
    }
  ]
}

Status: 401 (Invalid Request):

{
  "errors": [
    {
      "status": "INVALID_TOKEN",
      "errorMessage": "Invalid token (DIS-TZ-1009)"
    }
  ]
}

Status: 500 (Internal Server Error):

{
  "errors": [
    {
      "status": "INTERNAL_ERROR",
      "errorMessage": "Issue with internal services. Please try again after sometime (DIS-TZ-1008)"
    }
  ]
}

Response Fields

Below table lists the response fields returned:

Table 2.
Response Element	Description
responses[].id	Unique identifier for each address.
responses[].timezone.timezoneName	Name and abbreviation of the timezone for the given location coordinates; such as, Central Europe Time (CET/CEST), Hawaiian Standard Time (HST) etc. timezoneName can contain blank values. The blank values generally are displayed for locations that do not fall under any country or for ocean/water regions.
responses[].timezone.zoneType	Timezone Identifier. Timezones are typically identified by continent or ocean and then by the name of the largest city within the region containing the clocks. For example, America/New_York represents most of the US eastern time zone; America/Phoenix represents most of Arizona, which uses mountain time without daylight saving time (DST).
responses[].timezones[].dstOffset	For a given location coordinates, the offset in milliseconds for daylight saving. This can be 0 or positive or negative number. For example, for the US timezone - Central Time (CST/CDT), the dstOffset applies as follows: Daylight Saving Starting Date and Time: 8th March, 2015 (if it a Sunday), or first Sunday after 8th March, 2015: When the local standard time turns: Sunday, 8th March, 2015, 02:00:00 exactly, clocks get turned forward 1 hour to Sunday, 8th March 2015, 03:00:00 local daylight time instead. Daylight Saving Ending Date and Time: 1st November, 2015 (if it is a Sunday), or first Sunday after 1st November, 2015 When the local standard time turns: Sunday, 1st November, 2015, above 02:00:00, clocks get turned backward 1 hour to Sunday, 1st November, 2015, 01:00:00 local daylight time instead.
responses[].timezones[].matchedAddress.admin1	The largest geographic area, The largest geographic area, typically a state or province. New York or Maharashtra.typically a state or province. The largest geographic area, typically a state or province. New York or Maharashtra. New York or Maharashtra.
responses[].timezones[].matchedAddress.admin2	The secondary geographic area, typically a county or district. Douglas County or West Mumbai.
responses[].timezones[].matchedAddress.areaName4	Matched Address locality Name.
responses[].timezones[].matchedAddress.city	Matched Address city name.
responses[].timezones[].matchedAddress.country	Matched Address ISO country code.
responses[].timezones[].matchedAddress.formattedAddress	Matched Address combination of mainAddressLine and addressLastLine.
responses[].timezones[].matchedAddress.formattedLocationAddress	Matched Address main addressLine.
responses[].timezones[].matchedAddress.postCode	Matched Address Zip Code.
responses[].timezones[].matchedAddress.postCodeExt	Matched Address Zip Code extension.
responses[].timezones[].matchedAddress.street	Matched Address street name.
responses[].timezones[].timestamp	Input UTC time.
responses[].timezones[].utcOffset	For a given location coordinates, the offset in milliseconds from the UTC time. This can be a 0 or a positive or negative number.

Status Codes

Each response to a request contains an HTTP status code. The Timezone Service will return one of the following status codes:

Table 3.
Response	Status Code	Description
`OK`	200	The request was valid and results were found.
`Partial_Response`	206	The request was valid but partial results were found.
`Unauthorized`	401	Invalid Token
`ZERO_RESULTS`	200	The request was valid but no results were found.
`INVALID_REQUEST`	400	Invalid information was encountered in the request.
`INVALID_CLIENT_INPUT`	400	Request body or parameter format is not correct.
`INVALID_TOKEN`	401	Invalid Token was encountered.
`UNAUTHORIZED`	401	Unauthorized request encountered
`BATCH_SIZE_EXCEEDED`	413	Batch size exceeded for the request.
`INTERNAL_ERROR`	500	An internal erroroccurred.
`SERVICE_UNAVAILABLE`	503	Service is not available to serve the request.

Error Codes

Below are the common error codes (400 status codes) for Timezone API:

Table 4.
Status Code	Error
400	The request has missing argument(s) (DIS-TZ-1001)
400	Timestamp is not provided in the request (DIS-TZ-1002)
400	Coordinates are invalid (DIS-TZ-1003)
400	Coordinates are not provided in the request (DIS-TZ-1004)
400	Latitude is invalid (DIS-TZ-1005)
400	Longitude is invalid (DIS-TZ-1006)
400	Geometry is not provided in the request (DIS-TZ-1007)
400	Invalid value for objectId (DIS-TZ-1008)
400	Latitude is invalid (DIS-TZ-1009)
400	Country is not provided in the request (DIS-TZ-1010)
400	Requested Country is not supported (DIS-TZ-1011)
400	Address is missing (DIS-TZ-1012)
400	Request is not valid (DIS-TZ-1013)
400	Required body is not specified (DIS-TZ-1014)
400	The request contains more than the allowed number of addresses. Please resend the request with fewer addresses (DIS-TZ-1015)
400	Latitude is not provided in the request (DIS-TZ-1018)
400	Longitude is not provided in the request (DIS-TZ-1019)
400	Country is not provided in the request (DIS-TZ-1020)
400	Request is not valid (DIS-TZ-1023)
401	Invalid token (DIS-TZ-1009)
401	Not Authorized to perform this action (DIS-TZ-1012)
401	Invalid token (DIS-TZ-1017)
401	Not Authorized to perform this action (DIS-TZ-1022)
500	Issue with internal services. Please try again after some time (DIS-TZ-1008)
500	Issue with internal services. Please try again after sometime (DIS-TZ-1016)