---
title: "Retrieves the local time for a given address"
method: POST
path: "/v1/timezone/address"
tags: ["Time Zone"]
---

# Retrieves the local time for a given address

`POST /v1/timezone/address`

## Request

- Base URL: `https://api.cloud.precisely.com`
- URL: `https://api.cloud.precisely.com/v1/timezone/address`
- Auth: one of:
  - HTTP bearer
  - API key in header `Authorization`

This endpoint retrieves the local time of any location in the world for a given address. The input and retrieved time format is in milliseconds.

## Headers

- `X-Request-Id` string

## Request body

- TimezoneAddressRequest: Request for TimeZone Address
  - `addresses` AddressTime[], required: List of addresses to extract Timezone
    - `timestamp` integer, required: The timestamp in UTC milliseconds, representing the time for which the timezone needs to be determined.
    - `address` Address, required: Address details for timezone requests
      - `addressLines` string[]: Lines of the requested address, following the country's addressing standard.
      - `admin1` string: The largest geographic area, typically a state or province.
      - `admin2` string: The secondary geographic area, typically a county or district.
      - `city` string: The city or town associated with the address.
      - `borough` string: Unit of local government or other administrative subdivision.
      - `suburb` string: Mixed-use or residential area within commuting distance of a city or urban area.
      - `postalCode` string: Primary postal code.
      - `postalCodeExt` string: Extended postal code, if applicable. For example, in the US, a ZIP+4 is formatted as 80125-8012.
      - `placeName` string: If applicable, specifies the name of a candidate's place or building.
      - `country` string, required: ISO 3166-1 compliant country code (alpha-2, alpha-3, or numeric).
      - `id` string: Unique identifier for the request.
  - `preferences` Preferences: Preferences that will processed with the request
    - `maxResults` integer: The maximum number of candidates to return. Default = 1.
    - `returnAllInfo` boolean: Specifies whether to return all available information for each candidate.
    - `factoryDescription` FactoryDescription: Controls which address processor will process the request.
      - `label` string: Sets the addressing processor based on the configured data. Labels are case-sensitive and must be lowercase. Default is "".
      - `featureSpecific` object: Ability to map a feature to an address processor, based on specified label.
        - `GEOCODE` string
        - `PARSE` string
        - `VERIFY` string
        - `REVERSE_GEOCODE` string
        - `INTERACTIVE` string
        - `LOOKUP` string
    - `customPreferences` object: For use against any country dataset, define custom preferences to control additional functionality such as matching criteria, address casing, and enable functionality like DPV and SuiteLink.
    - `clientLocale` Locale: Represents a locale with language, script, country, and variant information.
      - `language` string: The ISO 639 language code.
      - `script` string: The ISO 15924 script code.
      - `country` string: The ISO 3166 country code.
      - `variant` string: The variant code for the locale.
      - `unicodeLocaleAttributes` string[]: The Unicode locale attributes.
      - `unicodeLocaleKeys` object: The Unicode locale keys.
      - `extensionKeys` object: The extension keys.
    - `clientCoordSysName` string: Specifies the coordinate system that you want to convert the geometry to. The format must be the European Petroleum Survey Group (EPSG) code or the SRID code. Default = EPSG:4326.
    - `distance` Distance: 'distance' displays the defined search radius (default is 5 meters). 'streetOffset' specifies the offset distance from the street segments to use in street-level geocoding. 'cornerOffset' specifies the distance to offset the street end points in street-level matching (default is 7 meters).
      - `value` number, double: Distance of the radius in which to search for a match. Default is 5.
      - `distanceUnit` 'FOOT' | 'METER' | 'MILE' | 'KILOMETER': Distance unit
    - `streetOffset` Distance: 'distance' displays the defined search radius (default is 5 meters). 'streetOffset' specifies the offset distance from the street segments to use in street-level geocoding. 'cornerOffset' specifies the distance to offset the street end points in street-level matching (default is 7 meters).
      - `value` number, double: Distance of the radius in which to search for a match. Default is 5.
      - `distanceUnit` 'FOOT' | 'METER' | 'MILE' | 'KILOMETER': Distance unit
    - `cornerOffset` Distance: 'distance' displays the defined search radius (default is 5 meters). 'streetOffset' specifies the offset distance from the street segments to use in street-level geocoding. 'cornerOffset' specifies the distance to offset the street end points in street-level matching (default is 7 meters).
      - `value` number, double: Distance of the radius in which to search for a match. Default is 5.
      - `distanceUnit` 'FOOT' | 'METER' | 'MILE' | 'KILOMETER': Distance unit
    - `fallbackToGeographic` boolean: Specifies whether to attempt to determine a geographic centroid when an address-level geocode cannot be determined. Optional.
    - `fallbackToPostal` boolean: Specifies whether to attempt to determine a post code centroid when an address-level geocode cannot be determined. Optional.
    - `matchMode` string: Match modes determine the leniency used to make a match between the input address and the reference data.
    - `originXY` number[]: XY coordinates of the origin address.
    - `returnOfAdditionalFields` string[]: This lets the user control which additional fields they want to have returned if they do not want to return all info.

## Response `200`

Timezone Retrieved Successfully For An Address

- TimezoneResponses: List of responses
  - `responses` TimezoneResponse[], required: List of timezone responses
    - `id` string, nullable: Id for the response
    - `status` 'OK' | 'ZERO_RESULTS': Represents the status of a response
    - `code` string: Error code from the service.
    - `detail` string: Error detail from the service.
    - `timezone` Timezone: Time Zone Response
      - `timezoneName` string, required: Name and abbreviation of the timezone.
      - `zoneType` string, required: Timezone Type
      - `utcOffset` integer, required: Offset in milliseconds from the UTC time
      - `dstOffset` integer, required: Offset in milliseconds for daylight saving
      - `timestamp` integer, required: Input UTC timestamp in milliseconds

## Other responses

- `206`: Timezone Retrieved Partially
- `400`: Invalid request
- `401`: Unauthorized: Invalid token
- `403`: Forbidden
- `413`: Request entity too large for Timezone Address API
- `429`: Too many requests
- `500`: Internal Server Error
- `503`: Service unavailable

---

[API](https://skmtc.dev/precisely/apis/time-zone-api.md) · [All operations](https://skmtc.dev/precisely/apis/time-zone-api/llms.txt) · [OpenAPI document](https://skmtc.dev/precisely/apis/time-zone-api/revisions/3471e4337d5b?raw)