{"openapi":"3.0.1","info":{"title":"Time Zone API","description":"The Time Zone API returns global time zones and UTC offsets with the input of a location coordinate or address, which is helpful for do-not-call, logistics, customer engagement applications, business processes, and workflows.\n\n<details>\n    <summary>Error Codes</summary>\n\nAPIs will return the following error codes in case of any error:\n\n\n| Error Code                 | Description\n|----------------------------|-------------------------------------------------------\n|DIS-1001                   |Unauthorized, Invalid token\n|DIS-1002                   |Not Authorized to access this API\n|DIS-1003                   |Issue with internal services\n|DIS-1004                   |Workspace Id is missing from Bearer Token\n|DIS-1005                   |Rate limit exceeded\n|DIS-1006                   |Unauthorized, Invalid key/secret\n|DIS-1007                   |API quota has been permanently exhausted. No further requests are allowed for trial user\n|DIS-1008                   |Invalid request ID, maximum allowed length is 38 characters\n|DIS-1009                   |Access blocked due to too many failed attempts. Please try again after sometime\n|DIS-1010                   |Workspace has been expired\n|DIS-TZ-1001                |Batch size must not exceed 25\n|DIS-TZ-1002                |Timestamp is not provided in the request\n|DIS-TZ-1003                |Coordinates are invalid\n|DIS-TZ-1004                |Coordinates are not provided in the request\n|DIS-TZ-1005                |Latitude is invalid\n|DIS-TZ-1006                |Longitude is invalid\n|DIS-TZ-1007                |Geometry is not provided in the request\n|DIS-TZ-1010                |Country is not provided in the request\n|DIS-TZ-1011                |Not able to identify requested country\n|DIS-TZ-1012                |Invalid value for searchRadiusUnit\n|DIS-TZ-1013                |Request is not valid\n|DIS-TZ-1014                |Required body is not specified\n|DIS-TZ-1015                |Required query value is not specified\n|DIS-TZ-1016                |Invalid or missing timestamp, it should be an integer\n</details>\n","version":"1.0"},"servers":[{"url":"https://api.cloud.precisely.com"}],"tags":[{"name":"Time Zone","description":"Operations related to Time Zone"}],"paths":{"/v1/timezone/address":{"post":{"tags":["Time Zone"],"summary":"Retrieves the local time for a given address","description":"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.","operationId":"timezoneAddresses","parameters":[{"name":"X-Request-Id","in":"header","description":"The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.","schema":{"type":"string"},"example":"e02f00d5-e3a9-4fd6-aen1-3e5451abee46"}],"requestBody":{"description":"Request Body for Timezone Address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimezoneAddressRequest"},"examples":{"example":{"value":{"addresses":[{"timestamp":1691138974831,"address":{"id":"1","addressLines":["950 Josephine Street Denver CO 80204"],"country":"USA"}}]}}}}},"required":true},"responses":{"200":{"description":"Timezone Retrieved Successfully For An Address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimezoneResponses"},"examples":{"example":{"value":{"responses":[{"id":"1","status":"OK","timezone":{"timezoneName":"Mountain Time (MST/MDT)","zoneType":"America/Denver","utcOffset":-25200000,"dstOffset":3600000,"timestamp":1691138974831}}]}}}}}},"206":{"description":"Timezone Retrieved Partially ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimezoneResponses"},"examples":{"example":{"value":{"responses":[{"id":"1","status":"OK","timezone":{"timezoneName":"Mountain Time (MST/MDT)","zoneType":"America/Denver","utcOffset":-25200000,"dstOffset":3600000,"timestamp":1691138974831}},{"id":"2","code":"DIS-TZ-1011","detail":"Not able to identify abc country"}]}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"656a097f-dee4-4d98-9a4a-caf4e8d145f9","errors":[{"code":"DIS-TZ-1011","detail":"Not able to identify abc country"}]}}}}}},"401":{"description":"Unauthorized: Invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"4d61c6732a07b0e9af2cb7de62b30d51","errors":[{"code":"DIS-1001","detail":"Unauthorized"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"4d61c6732a07b0e9af2cb7de62b30d15","errors":[{"code":"DIS-1002","detail":"Not Authorized to access this API"}]}}}}}},"413":{"description":"Request entity too large for Timezone Address API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"59750e82-97bf-4804-984a-b3a2a53bdf3a","errors":[{"code":"DIS-TZ-1001","detail":"Batch size must not exceed 25"}]}}}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"736ead9c-cba7-49a6-82bc-b3897bb16c37","errors":[{"code":"DIS-1005","detail":"Rate limit exceeded"}]}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"736ead9c-cba7-49a6-82bc-b3897bb16c73","errors":[{"code":"DIS-1003","detail":"Issue with internal services"}]}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"736ead9c-cba7-49a6-28bc-b3897bb16c73","errors":[{"code":"DIS-1003","detail":"Issue with internal services"}]}}}}}}},"security":[{"bearerAuth":[]},{"ApiKeyAuth":[]}]}},"/v1/timezone/location":{"post":{"tags":["Time Zone"],"summary":"Retrieves the local time of any location","description":"This endpoint retrieves the local time of any location in the world for a given latitude, longitude and time. The input and retrieved time format is in milliseconds.","operationId":"timezoneLocations","parameters":[{"name":"X-Request-Id","in":"header","description":"The X-Request-Id header is optional but incredibly useful for developers. It serves as a unique identifier for requests within our system. When you encounter any problems with your requests, providing us with the X-Request-Id will enable us to pinpoint the specific request in question without the need for extensive manual searching. This means faster and more efficient troubleshooting. The maximum allowed length is 38 characters.","schema":{"type":"string"},"example":"b62f00d5-e3a9-4fd6-aae0-3e5451abee46"}],"requestBody":{"description":"Request Body for Timezone Location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimezoneLocationRequest"},"examples":{"example":{"value":{"locations":[{"id":"1","timestamp":1691138974831,"geometry":{"coordinates":[-89.398528,40.633125]}}]}}}}},"required":true},"responses":{"200":{"description":"Timezone Retrieved Successfully For Location","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimezoneResponses"},"examples":{"example":{"value":{"responses":[{"id":"1","status":"OK","timezone":{"timezoneName":"Central Time (CST/CDT)","zoneType":"America/Chicago","utcOffset":-21600000,"dstOffset":3600000,"timestamp":1691138974831}}]}}}}}},"206":{"description":"Timezone Retrieved Partially ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TimezoneResponses"},"examples":{"example":{"value":{"responses":[{"id":"1","status":"OK","timezone":{"timezoneName":"Central Time (CST/CDT)","zoneType":"America/Chicago","utcOffset":-21600000,"dstOffset":3600000,"timestamp":1691138974831}},{"id":"2","code":"DIS-TZ-1006","detail":"Longitude is invalid"}]}}}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"656a097f-dee4-4d98-9a4a-caf4e8d145f4","errors":[{"code":"DIS-TZ-1006","detail":"Longitude is invalid"}]}}}}}},"401":{"description":"Invalid token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"4d61c6732a07b0e9af2cb7de62b30d51","errors":[{"code":"DIS-1001","detail":"Unauthorized"}]}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"4d61c6732a07b0e9af2cb7de62b30d15","errors":[{"code":"DIS-1002","detail":"Not Authorized to access this API"}]}}}}}},"413":{"description":"Request entity too large for Timezone Location API","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"59750e82-97bf-4804-984a-b3a2a53bdf3a","errors":[{"code":"DIS-TZ-1001","detail":"Batch size must not exceed 25"}]}}}}}},"429":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"736ead9c-cba7-49a6-82bc-b3897bb16c37","errors":[{"code":"DIS-1005","detail":"Rate limit exceeded"}]}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"736ead9c-cba7-49a6-82bc-b3897bb16c73","errors":[{"code":"DIS-1003","detail":"Issue with internal services"}]}}}}}},"503":{"description":"Service unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"example":{"value":{"id":"736ead9c-cba7-49a6-28bc-b3897bb16c73","errors":[{"code":"DIS-1003","detail":"Issue with internal services"}]}}}}}}},"security":[{"bearerAuth":[]},{"ApiKeyAuth":[]}]}}},"components":{"schemas":{"Address":{"required":["country"],"type":"object","properties":{"addressLines":{"type":"array","description":"Lines of the requested address, following the country's addressing standard.","example":["123 Main St","HASTINGS MN, United States"],"items":{"type":"string"}},"admin1":{"type":"string","description":"The largest geographic area, typically a state or province.","example":"Minnesota"},"admin2":{"type":"string","description":"The secondary geographic area, typically a county or district.","example":"Dakota County"},"city":{"type":"string","description":"The city or town associated with the address.","example":"HASTINGS"},"borough":{"type":"string","description":"Unit of local government or other administrative subdivision.","example":"Ward 5"},"suburb":{"type":"string","description":"Mixed-use or residential area within commuting distance of a city or urban area.","example":"Downtown"},"postalCode":{"type":"string","description":"Primary postal code.","example":"55033"},"postalCodeExt":{"type":"string","description":"Extended postal code, if applicable. For example, in the US, a ZIP+4 is formatted as 80125-8012.","example":"8012"},"placeName":{"type":"string","description":"If applicable, specifies the name of a candidate's place or building.","example":"Central Plaza"},"country":{"type":"string","description":"ISO 3166-1 compliant country code (alpha-2, alpha-3, or numeric).","example":"USA"},"id":{"type":"string","description":"Unique identifier for the request.","example":"1"}},"description":"Address details for timezone requests"},"AddressTime":{"required":["address","timestamp"],"type":"object","properties":{"timestamp":{"type":"integer","description":"The timestamp in UTC milliseconds, representing the time for which the timezone needs to be determined.","format":"int64","example":1691138974843},"address":{"description":"The address details for which the timezone needs to be extracted.","allOf":[{"$ref":"#/components/schemas/Address"}]}},"description":"Details about the address and time to be processed for timezone extraction."},"Distance":{"type":"object","properties":{"value":{"type":"number","description":"Distance of the radius in which to search for a match. Default is 5.","format":"double","example":5},"distanceUnit":{"$ref":"#/components/schemas/DistanceUnit"}},"description":"'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)."},"DistanceUnit":{"type":"string","description":"Distance unit","example":"METER","enum":["FOOT","METER","MILE","KILOMETER"]},"ErrorDetail":{"required":["detail"],"type":"object","properties":{"code":{"type":"string","description":"A unique code representing the specific error.","example":"DIS-1001"},"detail":{"type":"string","description":"A detailed message describing the error.","example":"Unauthorized"}},"description":"Error details."},"ErrorResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the error.","example":"ad45c1aded938181a05f256e5a1b594d"},"errors":{"type":"array","description":"List of errors ","items":{"$ref":"#/components/schemas/ErrorDetail"}}},"description":"Error response."},"FactoryDescription":{"type":"object","properties":{"label":{"type":"string","description":"Sets the addressing processor based on the configured data. Labels are case-sensitive and must be lowercase. Default is \"\".","example":"asd"},"featureSpecific":{"description":"Ability to map a feature to an address processor, based on specified label.","example":{"LOOKUP":"ggs"},"allOf":[{"properties":{"GEOCODE":{"type":"string"},"PARSE":{"type":"string"},"VERIFY":{"type":"string"},"REVERSE_GEOCODE":{"type":"string"},"INTERACTIVE":{"type":"string"},"LOOKUP":{"type":"string"}}}]}},"description":"Controls which address processor will process the request."},"GeometryCoordinates":{"required":["coordinates"],"type":"object","properties":{"coordinates":{"type":"array","description":"Location Coordinates i.e. Longitude(-180 to 180) and Latitude(-90 to 90) of the Location. (WGS 84 datum/EPSG:4326 coordinate system)","example":[-93.176563,44.709968],"items":{"type":"number","format":"double"}}},"description":"Geometry Details"},"Locale":{"title":"Locale","type":"object","properties":{"language":{"type":"string","description":"The ISO 639 language code.","example":"en"},"script":{"type":"string","description":"The ISO 15924 script code.","example":"Latn"},"country":{"type":"string","description":"The ISO 3166 country code.","example":"US"},"variant":{"type":"string","description":"The variant code for the locale.","example":"POSIX"},"unicodeLocaleAttributes":{"type":"array","description":"The Unicode locale attributes.","example":["attribute1","attribute2"],"items":{"type":"string"}},"unicodeLocaleKeys":{"type":"object","additionalProperties":{"type":"string"},"description":"The Unicode locale keys.","example":{"nu":"thai"}},"extensionKeys":{"type":"object","additionalProperties":{"type":"string"},"description":"The extension keys.","example":{"x":"private-use"}}},"description":"Represents a locale with language, script, country, and variant information."},"LocationTime":{"required":["geometry","timestamp"],"type":"object","properties":{"id":{"type":"string","description":"Id of the request.","nullable":true,"example":"1"},"timestamp":{"type":"integer","description":"Specifies UTC time in milliseconds.","format":"int64","example":1691138974831},"geometry":{"description":"Geometry coordinates","allOf":[{"$ref":"#/components/schemas/GeometryCoordinates"}]}},"description":"Locations to be processed"},"Preferences":{"type":"object","properties":{"maxResults":{"type":"integer","description":"The maximum number of candidates to return. Default = 1.","format":"int32","example":1},"returnAllInfo":{"type":"boolean","description":"Specifies whether to return all available information for each candidate.","example":true},"factoryDescription":{"description":"description of address processor to process the request.","allOf":[{"$ref":"#/components/schemas/FactoryDescription"}]},"customPreferences":{"type":"object","additionalProperties":{"type":"string"},"description":"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.","example":{"DATA_OPTION":"PREMIUM"}},"clientLocale":{"title":"Locale","description":"Specifies the locale value. For example, specify \"th\" for the Thai language.","allOf":[{"$ref":"#/components/schemas/Locale"}]},"clientCoordSysName":{"type":"string","description":"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.","example":"EPSG:4326"},"distance":{"description":"distance the defined search radius (default is 5 meters)..","allOf":[{"$ref":"#/components/schemas/Distance"}]},"streetOffset":{"description":"streetOffset specifies the offset distance from the street segments to use in street-level geocoding (Default 5 meters).","allOf":[{"$ref":"#/components/schemas/Distance"}]},"cornerOffset":{"description":"Specifies the distance to offset the street end points in street-level matching (default is 7 meters).","allOf":[{"$ref":"#/components/schemas/Distance"}]},"fallbackToGeographic":{"type":"boolean","description":"Specifies whether to attempt to determine a geographic centroid when an address-level geocode cannot be determined. Optional.","example":false},"fallbackToPostal":{"type":"boolean","description":"Specifies whether to attempt to determine a post code centroid when an address-level geocode cannot be determined. Optional.","example":false},"matchMode":{"type":"string","description":"Match modes determine the leniency used to make a match between the input address and the reference data.","example":"EXACT"},"originXY":{"type":"array","description":"XY coordinates of the origin address.","example":[0.0,0.0],"items":{"type":"number","format":"double"}},"returnOfAdditionalFields":{"type":"array","description":"This lets the user control which additional fields they want to have returned if they do not want to return all info.","example":["RESULT_CODE","PRECISION_CODE"],"items":{"type":"string"}}},"description":"Preferences that will processed with the request"},"Status":{"type":"string","description":"Represents the status of a response","example":"OK","enum":["OK","ZERO_RESULTS"]},"Timezone":{"required":["dstOffset","timestamp","timezoneName","utcOffset","zoneType"],"type":"object","properties":{"timezoneName":{"type":"string","description":"Name and abbreviation of the timezone.","example":"Mountain Time (MST/MDT)"},"zoneType":{"type":"string","description":"Timezone Type","example":"America/Denve"},"utcOffset":{"type":"integer","description":"Offset in milliseconds from the UTC time","format":"int64","example":-25200000},"dstOffset":{"type":"integer","description":"Offset in milliseconds for daylight saving","format":"int64","example":3600000},"timestamp":{"type":"integer","description":"Input UTC timestamp in milliseconds","format":"int64","example":1691138974831}},"description":"Time Zone Response"},"TimezoneAddressRequest":{"required":["addresses"],"type":"object","properties":{"addresses":{"minItems":1,"type":"array","description":"List of addresses to extract Timezone","items":{"$ref":"#/components/schemas/AddressTime"}},"preferences":{"description":"Preferences for the Timezone by-address operation","nullable":true,"allOf":[{"$ref":"#/components/schemas/Preferences"}]}},"description":"Request for TimeZone Address"},"TimezoneLocationRequest":{"required":["locations"],"type":"object","properties":{"locations":{"minItems":1,"type":"array","description":"List of locations to extract timezone","items":{"$ref":"#/components/schemas/LocationTime"}}},"description":"Request for TimeZone Location"},"TimezoneResponse":{"type":"object","properties":{"id":{"type":"string","description":"Id for the response","nullable":true,"example":"16"},"status":{"$ref":"#/components/schemas/Status"},"code":{"type":"string","description":"Error code from the service.","example":"DIS-1003"},"detail":{"type":"string","description":"Error detail from the service.","example":"Issue with internal services"},"timezone":{"description":"Timezone Response","allOf":[{"$ref":"#/components/schemas/Timezone"}]}},"description":"Responses for requests"},"TimezoneResponses":{"required":["responses"],"type":"object","properties":{"responses":{"type":"array","description":"List of timezone responses","items":{"$ref":"#/components/schemas/TimezoneResponse"}}},"description":"List of responses"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","description":"Pass the value in the following format: Apikey <base64(api_key:api_secret)>.","name":"Authorization","in":"header"},"bearerAuth":{"type":"http","description":"Pass the value as JWT Bearer Token.","scheme":"bearer"}}}}