Get Timezone Info

Returns timezone information for one or more North American phone numbers

POST /v1.5/GeoScrub/GetTimeZoneInfo

Returns timezone information for one or more North America phone numbers

cURL

curl --request POST \
  --url https://dataapi.dncscrub.com/v1.5/GeoScrub/GetTimeZoneInfo \
  --header 'Content-Type: application/json' \
  --data '
{
  "PhoneList": [
    "<string>"
  ],
  "OverwriteTodaysTime": "2023-11-07T05:31:56Z"
}
'

200

[
  {
    "PhoneNumber": "<string>",
    "TZName": "<string>",
    "StateProvince": "<string>",
    "UTCOffset": "<string>",
    "UTCOffsetInMinutes": 123,
    "HasDST": true,
    "NextStartDateDST": "2023-11-07T05:31:56Z",
    "EndStartDateDST": "2023-11-07T05:31:56Z",
    "LATA": "<string>",
    "RateCenterLIR": "<string>"
  }
]

Response Fields

Every input phone produces exactly one row in the response. Inspect Status to decide how to handle each row.

Field	Type	Description
PhoneNumber	string	The 10-digit phone number the row applies to
TZName, StateProvince, UTCOffset, UTCOffsetInMinutes, HasDST, NextStartDateDST, EndStartDateDST, LATA, RateCenterLIR	various	Timezone metadata. Populated only when Status is "OK"; left at default / null values for any non-OK row
Status	string	Outcome code for the row. See the table below
StatusMessage	string	Human-readable explanation when Status is not "OK". null when Status is "OK"

Status Values

Status	Meaning	Recommended client action
OK	Row processed successfully. Timezone fields are valid.	Use the result.
INVALID_PHONE	Phone number failed format validation.	Skip; flag the source list for cleanup.
TOLL_FREE	Phone is in a toll-free NANP area code (8YY). Non-geographic, so no timezone exists.	Skip; do not retry.
UNKNOWN_NXX	The NPA-NXX is not in our prefix master list. Because the master list is refreshed from definitive telco data, this almost always means the NXX is unassigned/invalid.	Skip; flag the source list for cleanup.

Per-row Status replaces the older behavior where a single bad phone caused the entire batch to return HTTP 400. The endpoint now returns 200 with one row per input phone; inspect Status to decide which rows are usable. HTTP 400 is still returned for batch-level errors (missing body, empty list, more than 1000 phones).

Headers

loginId · string

LoginId (aka APIKey)

Body

application/jsontext/jsonapplication/*+json

Object of phone numbers whose timezones we query

PhoneList · string[] | null

OverwriteTodaysTime · string<date-time> | null

Response

200

application/json

Success

PhoneNumber · string | null

TZName · string | null

StateProvince · string | null

UTCOffset · string | null

UTCOffsetInMinutes · integer<int32>

HasDST · boolean

NextStartDateDST · string<date-time> | null

EndStartDateDST · string<date-time> | null

LATA · string | null

RateCenterLIR · string | null