SearchCtrl+K

APIs/Timezone APIs/Timezone Lookup API/Reference

Timezone Converter API Reference

Convert a timestamp from one timezone to another using any supported location identifier - timezone names, GPS coordinates, city or address strings, IATA airport codes, ICAO codes, or UN/LOCODEs.

GEThttps://api.apifreaks.com/v1.0/timezone/converter

Test

The Timezone Converter API takes a source timezone, a destination timezone, and an optional timestamp, then returns the converted time along with the hour and minute difference between the two zones. Omit the time parameter to convert the current time. The same 6 input methods available in the Timezone Lookup API are supported for both source and destination - pass matching _from and _to parameter pairs.

Getting Started

Authentication

Authorize every request with your API key, passed either as a header or as a query parameter:

Header - X-apiKey
Query parameter - apiKey

API Version

This is version v1.0 of the API.

LANGUAGE

curl -X 'GET' \
  'https://api.apifreaks.com/v1.0/timezone/converter?tz=America%2FNew_York' \
  -H 'X-apiKey: API-KEY'

Response

{
  "original_time": "2024-09-01 00: 00: 00",
  "converted_time": "2024-09-01 05: 00: 00",
  "diff_hour": 5,
  "diff_min": 300
}

API Request

Query Parameters

All parameters are optional query string parameters. You must provide a matching _from/_to pair from one of the supported input methods: timezone names (tz_from/tz_to), coordinates (lat_from/long_from and lat_to/long_to), location addresses (location_from/location_to), IATA codes (iata_from/iata_to), ICAO codes (icao_from/icao_to), or UN/LOCODEs (locode_from/locode_to).

formatoptionalStringdefault: json

Response format: 'json' (default) or 'xml'.

timeoptionalString

Time value for conversion. Two formats supported:

1.yyyy-MM-dd HH:mm
2.yyyy-MM-dd HH:mm:ss
3.Omit to convert the current time.

tz_fromoptionalString

From timezone name (IANA format) for conversion using timezone name

tz_tooptionalString

To timezone name (IANA format) for conversion using timezone name

lat_fromoptionalInteger

From latitude coordinate for conversion using location coordinates

long_fromoptionalInteger

From longitude coordinate for conversion using location coordinates

lat_tooptionalInteger

To latitude coordinate for conversion using location coordinates

long_tooptionalInteger

To longitude coordinate for conversion using location coordinates

location_fromoptionalString

From location address for conversion using location address

location_tooptionalString

To location address for conversion using location address

iata_fromoptionalString

From IATA airport code (3-letter) for conversion using airport code

iata_tooptionalString

To IATA airport code (3-letter) for conversion using airport code

icao_fromoptionalString

From ICAO airport code (4-letter) for conversion using airport code

icao_tooptionalString

To ICAO airport code (4-letter) for conversion using airport code

locode_fromoptionalString

From UN/LO CODE (5-letter) for conversion using location code

locode_tooptionalString

To UN/LO CODE (5-letter) for conversion using location code

API Response Schema

A successful request returns a 200 OK response with a JSON object containing four fields. See the response preview on the right for the full JSON structure.

original_time

Stringmandatory

The original input time before conversion

converted_time

Stringmandatory

The resulting time after conversion to the target timezone

diff_hour

Integermandatory

The time difference between the two timezones in hours

diff_min

Integermandatory

The time difference between the two timezones in minutes

Custom Response Headers

Besides the response body, every response carries custom headers you can use to track credit usage, and concurrency usage on endpoints that enforce a concurrency limit. See the Custom Response Headers documentation and the endpoints with concurrency limits for more details.

X-Concurrent-Threadsheaderconcurrency-limited endpoints

Specifies the maximum number of concurrent requests allowed.

X-Concurrent-Threads-Activeheaderconcurrency-limited endpoints

Indicates the number of active concurrent requests being processed.

X-AF-Credits-Costheaderall responses

Specifies the number of credits consumed by the current request.

Error Status & Codes

See the HTTP Status Codes documentation for a complete reference of common API errors and HTTP status codes.

400

Parameters' combination is not complete. 'tz_from' and 'tz_to' or 'location_from' and 'location_to' or 'lat_from' and 'long_from' and 'lat_to' and 'long_to' or 'locode_from' and 'locode_to' or 'iata_from' and 'iata_to' or 'icao_from' and 'icao_to' combinations must be provided.

400

Check whether your input values are correct; source_time_zone = Invalid/TZ, destined_time_zone = Asia/Karachi, date_time = null

400

Provided lat_from (999) or long_from (0) is not valid. Latitude must be between -90.0 and +90.0 and longitude must be between -180.0 and +180.0.

400

We couldn't find the (from) location (ZZZNOTEXIST). Try a city or state level address only.

400

'Data not found for the provided airport code: XXX Please contact at support@apifreaks.com if provided airport code exists.'

Timezone Converter API Reference

Convert a timestamp from one timezone to another using any supported location identifier - timezone names, GPS coordinates, city or address strings, IATA airport codes, ICAO codes, or UN/LOCODEs.

GEThttps://api.apifreaks.com/v1.0/timezone/converter

Test

Getting Started

Authentication

Authorize every request with your API key, passed either as a header or as a query parameter:

Header - X-apiKey
Query parameter - apiKey

API Version

This is version v1.0 of the API.

LANGUAGE

curl -X 'GET' \
  'https://api.apifreaks.com/v1.0/timezone/converter?tz=America%2FNew_York' \
  -H 'X-apiKey: API-KEY'

Response

{
  "original_time": "2024-09-01 00: 00: 00",
  "converted_time": "2024-09-01 05: 00: 00",
  "diff_hour": 5,
  "diff_min": 300
}

API Request

Query Parameters

formatoptionalStringdefault: json

Response format: 'json' (default) or 'xml'.

timeoptionalString

Time value for conversion. Two formats supported:

1.yyyy-MM-dd HH:mm
2.yyyy-MM-dd HH:mm:ss
3.Omit to convert the current time.

tz_fromoptionalString

From timezone name (IANA format) for conversion using timezone name

tz_tooptionalString

To timezone name (IANA format) for conversion using timezone name

lat_fromoptionalInteger

From latitude coordinate for conversion using location coordinates

long_fromoptionalInteger

From longitude coordinate for conversion using location coordinates

lat_tooptionalInteger

To latitude coordinate for conversion using location coordinates

long_tooptionalInteger

To longitude coordinate for conversion using location coordinates

location_fromoptionalString

From location address for conversion using location address

location_tooptionalString

To location address for conversion using location address

iata_fromoptionalString

From IATA airport code (3-letter) for conversion using airport code

iata_tooptionalString

To IATA airport code (3-letter) for conversion using airport code

icao_fromoptionalString

From ICAO airport code (4-letter) for conversion using airport code

icao_tooptionalString

To ICAO airport code (4-letter) for conversion using airport code

locode_fromoptionalString

From UN/LO CODE (5-letter) for conversion using location code

locode_tooptionalString

To UN/LO CODE (5-letter) for conversion using location code

API Response Schema

A successful request returns a 200 OK response with a JSON object containing four fields. See the response preview on the right for the full JSON structure.

original_time

Stringmandatory

The original input time before conversion

converted_time

Stringmandatory

The resulting time after conversion to the target timezone

diff_hour

Integermandatory

The time difference between the two timezones in hours

diff_min

Integermandatory

The time difference between the two timezones in minutes

Custom Response Headers

X-Concurrent-Threadsheaderconcurrency-limited endpoints

Specifies the maximum number of concurrent requests allowed.

X-Concurrent-Threads-Activeheaderconcurrency-limited endpoints

Indicates the number of active concurrent requests being processed.

X-AF-Credits-Costheaderall responses

Specifies the number of credits consumed by the current request.

Error Status & Codes

See the HTTP Status Codes documentation for a complete reference of common API errors and HTTP status codes.

400

Check whether your input values are correct; source_time_zone = Invalid/TZ, destined_time_zone = Asia/Karachi, date_time = null

400

Provided lat_from (999) or long_from (0) is not valid. Latitude must be between -90.0 and +90.0 and longitude must be between -180.0 and +180.0.

400

We couldn't find the (from) location (ZZZNOTEXIST). Try a city or state level address only.

400

'Data not found for the provided airport code: XXX Please contact at support@apifreaks.com if provided airport code exists.'

Quick Links

Quick Links

Timezone Converter API Reference

Getting Started

Authentication

API Version

API Request

Query Parameters

API Response Schema

Custom Response Headers

Error Status & Codes

Quick Links

Quick Links

Timezone Converter API Reference

Getting Started

Authentication

API Version

API Request

Query Parameters

API Response Schema

Custom Response Headers

Error Status & Codes

Timezone Converter API Reference

Getting Started

Authentication

API Version

API Request

Query Parameters

API Response Schema

Custom Response Headers

Error Status & Codes

More APIs in This Category

Timezone Lookup API

Timezone Converter API Reference

Getting Started

Authentication

API Version

API Request

Query Parameters

API Response Schema

Custom Response Headers

Error Status & Codes

More APIs in This Category

Timezone Lookup API