---
title: Timezone Converter API Reference
version: 1.0.0
description: Convert a timestamp from one timezone to another using timezone names, GPS coordinates, location addresses, IATA/ICAO airport codes, or UN/LOCODEs. Returns the converted time, the original time, and the hour/minute difference between the two timezones. Supports pair-based lookups --- provide source and target using any supported identifier type (e.g., `tz_from` + `tz_to` for IANA names, `lat_from`/`long_from` + `lat_to`/`long_to` for coordinates, `iata_from` + `iata_to` for airport codes). If no `time` parameter is provided the API converts the current time.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 2
---

## Table of Contents

- [Timezone Converter API Reference v1.0.0](#timezone-converter-api-reference-v100)
  - [Authentication](#authentication)
  - [Timezone APIs](#timezone-apis)
    - [convertTimezone](#converttimezone)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [TimezoneConversionResponse](#timezoneconversionresponse)
    - [ErrorResponse](#errorresponse)



# Timezone Converter API Reference v1.0.0

Convert a timestamp from one timezone to another using timezone names, GPS coordinates, location addresses, IATA/ICAO airport codes, or UN/LOCODEs. Returns the converted time, the original time, and the hour/minute difference between the two timezones. Supports pair-based lookups --- provide source and target using any supported identifier type (e.g., `tz_from` + `tz_to` for IANA names, `lat_from`/`long_from` + `lat_to`/`long_to` for coordinates, `iata_from` + `iata_to` for airport codes). If no `time` parameter is provided the API converts the current time.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## Timezone APIs

### convertTimezone

`GET /timezone/converter`

*Convert a timestamp from one timezone to another using any supported location identifier*

Convert a given time from one timezone to another using timezone names, GPS coordinates, location addresses, IATA/ICAO airport codes, or UN/LOCODEs.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|format|query|string|false|Format of the response. Possible values: json, xml.|
|time|query|string|false|Time to convert in yyyy-MM-dd HH:mm or yyyy-MM-dd HH:mm:ss format. Omit to convert the current time.|
|tz_from|query|string|false|Source timezone name in IANA format (e.g., Asia/Kolkata) to convert from.|
|tz_to|query|string|false|Target timezone name in IANA format (e.g., America/New_York) to convert to.|
|lat_from|query|number(float)|false|Latitude of source location for coordinate-based conversion.|
|long_from|query|number(float)|false|Longitude of source location for coordinate-based conversion.|
|lat_to|query|number(float)|false|Latitude of target location for coordinate-based conversion.|
|long_to|query|number(float)|false|Longitude of target location for coordinate-based conversion.|
|location_from|query|string|false|Source location address (city and country) for address-based conversion.|
|location_to|query|string|false|Target location address (city and country) for address-based conversion.|
|iata_from|query|string|false|Source IATA airport code (3-letter, e.g., JFK) for airport-based conversion.|
|iata_to|query|string|false|Target IATA airport code (3-letter) for airport-based conversion.|
|icao_from|query|string|false|Source ICAO airport code (4-letter, e.g., KJFK) for airport-based conversion.|
|icao_to|query|string|false|Target ICAO airport code (4-letter) for airport-based conversion.|
|locode_from|query|string|false|Source UN/LOCODE (5-letter) for location code-based conversion.|
|locode_to|query|string|false|Target UN/LOCODE (5-letter) for location code-based conversion.|

##### Enumerated Values

|Parameter|Value|
|---|---|
|format|json|
|format|xml|

> Example responses

> Successful timezone conversion response

```json
{
  "original_time": "2026-07-24 12:00:00",
  "converted_time": "2026-07-24 17:00:00",
  "diff_hour": 5,
  "diff_min": 300
}
```

```json
{
  "original_time": "2026-07-24 12:00:00",
  "converted_time": "2026-07-24 02:30:00",
  "diff_hour": 9.5,
  "diff_min": 570
}
```

> Bad Request — Incomplete parameter combination, invalid timezone name, invalid coordinates, or location address not found

```json
{
  "message": "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."
}
```

```json
{
  "message": "Check whether your input values are correct; source_time_zone = Invalid/TZ, destined_time_zone = Asia/Karachi, date_time = null"
}
```

```json
{
  "message": "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."
}
```

```json
{
  "message": "We couldn't find the (from) location (ZZZNOTEXIST). Try a city or state level address only."
}
```

```json
{
  "message": "We couldn't find the (to) location (ZZZNOTEXIST). Try a city or state level address only."
}
```

> Not Found — Airport (IATA/ICAO) code or UN/LOCODE has no matching data

```json
{
  "message": "'Data not found for the provided airport code: XXX Please contact at support@ipgeolocation.io if provided airport code exists.'"
}
```

```json
{
  "message": "'Data not found for the provided LO code: ZZZZZ Please contact at support@ipgeolocation.io if provided LO code exists.'"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful timezone conversion response|[TimezoneConversionResponse](#timezoneconversionresponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Incomplete parameter combination, invalid timezone name, invalid coordinates, or location address not found|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found — Airport (IATA/ICAO) code or UN/LOCODE has no matching data|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### TimezoneConversionResponse

Timezone conversion result containing original and converted timestamps with the difference.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|original_time|string|true|none|The original date and time before any conversion, in yyyy-MM-dd HH:mm:ss format.|
|converted_time|string|true|none|The date and time after conversion to the target timezone, in yyyy-MM-dd HH:mm:ss format.|
|diff_hour|number(float)|true|none|The absolute difference in hours between the source and target timezones, always non-negative regardless of conversion direction. Can be fractional for half-hour/quarter-hour offset timezones (e.g. 9.5 for Asia/Kolkata to America/New_York).|
|diff_min|integer|true|none|The absolute difference between the source and target timezones expressed in total minutes (not a remainder — always diff_hour * 60), always non-negative regardless of conversion direction.|

### ErrorResponse

Standard error envelope returned by the API on failed requests. 

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|