IP Address API: Ensuring Accurate Retrievals and Verifications

The IP address API enables you to request an IP address and get the details about the IP address in return. If you don't specify an IP address our system will try to find your users IP address.

For certain programming languages / request methods we recommend that you specify the IP address. The IP address returned by our system could be your servers local IP address, so please double check with a friend not located where you are.

Data
Please URL encode all parameter values.

Get users location, time zone and date/time details

Returns location, timezone and datetime information. If IP address is not defined, the code will detect the users IP address. Date/time defaults to when the request was made. 

$ curl https://timezoneapi.io/api/ip/?token=TOKEN

// Get IP address
$ip_address = getenv('HTTP_CLIENT_IP') ?: getenv('HTTP_X_FORWARDED_FOR') ?: getenv('HTTP_X_FORWARDED') ?: getenv('HTTP_FORWARDED_FOR') ?: getenv('HTTP_FORWARDED') ?: getenv('REMOTE_ADDR');

// Get JSON object
$jsondata = file_get_contents("http://timezoneapi.io/api/ip/?" . $ip_address . '&token=TOKEN');

// Decode
$data = json_decode($jsondata, true);

// Request OK?
if($data['meta']['code'] == '200'){

	// Example: Get the city parameter
	echo "City: " . $data['data']['city'] . "<br>";

	// Example: Get the users time
	echo "Time: " . $data['data']['datetime']['date_time_txt'] . "<br>";

}

// Require
const request = require('request');

// Request
request('https://timezoneapi.io/api/ip/?token=TOKEN', function(err, res, dat){

	// Parse
	var data = JSON.parse(dat);

	// Request OK?
    if(data.meta.code == '200'){

        // Log
        console.log(data);

        // Example: Get the city parameter
        var city = data.data.city;

        // Example: Get the users time
        var time = data.data.datetime.date_time_txt;

    }

});

// Get JSON object
$.getJSON('https://timezoneapi.io/api/ip/?token=TOKEN', function(data){

	// Request OK?
	if(data.meta.code == '200'){

		// Log
		console.log(data);

		// Example: Get the city parameter
		var city = data.data.city;
		alert(city);

		// Example: Get the users time
		var time = data.data.datetime.date_time_txt;
		alert(time);

	}

});

# Require
require 'json'
require 'open-uri'

# Get JSON and parse
data = JSON.parse(open('https://timezoneapi.io/api/ip/?token=TOKEN').read)

# If OK, get values
if data['meta']['code'] = 200
	city = data['data']['city']
	puts city
	time = data['data']['datetime']['date_time_txt']
	puts time
end

# Import
import requests

# Get
response = requests.get('https://timezoneapi.io/api/ip/?token=TOKEN')

# Parse JSON
data = response.json()

# If ok, get values
if data['meta']['code'] = 200:
	City = data['data']['city']
	print City
	Time = data['data']['datetime']['date_time_txt']
	print Time

Returns

{
    "meta": {
        "code": "200"
    },
    "data": {
        "ip": "66.220.144.0",
        "city": "Menlo Park",
        "postal": "94025",
        "state": "California",
        "state_code": "CA",
        "country": "United States",
        "country_code": "US",
        "location": "37.459,-122.1781",
        "timezone": {
            "id": "America\/Los_Angeles",
            "location": "34.05222,-118.24278",
            "country_code": "US",
            "country_name": "United States of America",
            "iso3166_1_alpha_2": "US",
            "iso3166_1_alpha_3": "USA",
            "un_m49_code": "840",
            "itu": "USA",
            "marc": "xxu",
            "wmo": "US",
            "ds": "USA",
            "phone_prefix": "1",
            "fifa": "USA",
            "fips": "US",
            "gual": "259",
            "ioc": "USA",
            "currency_alpha_code": "USD",
            "currency_country_name": "UNITED STATES",
            "currency_minor_unit": "2",
            "currency_name": "US Dollar",
            "currency_code": "840",
            "independent": "Yes",
            "capital": "Washington",
            "continent": "NA",
            "tld": ".us",
            "languages": "en-US,es-US,haw,fr",
            "geoname_id": "6252001",
            "edgar": ""
        },
        "datetime": {
            "date": "12\/05\/2024",
            "date_time": "12\/05\/2024 01:35:13",
            "date_time_txt": "Monday, December 5, 2024 01:35:13",
            "date_time_wti": "Mon, 05 Dec 2024 01:35:13 -0800",
            "date_time_ymd": "2024-12-05T01:35:13-08:00",
            "time": "01:35:13",
            "month": "12",
            "month_wilz": "12",
            "month_abbr": "Dec",
            "month_full": "December",
            "month_days": "31",
            "day": "5",
            "day_wilz": "05",
            "day_abbr": "Mon",
            "day_full": "Monday",
            "year": "2024",
            "year_abbr": "16",
            "hour_12_wolz": "1",
            "hour_12_wilz": "01",
            "hour_24_wolz": "1",
            "hour_24_wilz": "01",
            "hour_am_pm": "am",
            "minutes": "35",
            "seconds": "13",
            "week": "49",
            "offset_seconds": "-28800",
            "offset_minutes": "-480",
            "offset_hours": "-8",
            "offset_gmt": "-08:00",
            "offset_tzid": "America\/Los_Angeles",
            "offset_tzab": "PST",
            "offset_tzfull": "Pacific Standard Time",
            "tz_string": "PST8PDT,M3.3.0/2,M11.2.0/2",
            "dst": "false",
            "dst_observes": "true",
            "timeday_spe": "late_night",
            "timeday_gen": "night"
        }
    }
}

Parameters

Parameter
Description
token
Mandatory.

https://timezoneapi.io/api/ip/?token=12345678
ip
Optional.

https://timezoneapi.io/api/ip/?66.220.144.0

or

https://timezoneapi.io/api/ip/?ip=66.220.144.0

If IP is not defined, the system will detect the users IP address.
date
Optional.

https://timezoneapi.io/api/ip/?date=03/31/2017

Lets you set the date/time to a specific date and time. If date is not defined, the code will default to when the request was made.

Accepts most date / time formats. We recommend using mm/dd/yyyy or mm/dd/yyyy mm:hh:ss.

Dates seperated with "/"" are interpreted as "mm/dd/yyyy". Dates seperated with "-"" are interpreted as "dd/mm/yyyy".
output
Optional.

Lets you set the header output format. Default is application/json.
Options are json or text.
Example: https://timezoneapi.io/api/ip/?ip=66.220.144.0&output=text
only
Optional.

Lets you choose which fields to output. In below example we only need to output ip city and children from the timezone and datetime objects.

Example: /?only=ip,city,timezone(id,location),datetime(date_time,tz_string)

Output variables

Variable
Description
meta
Object
code
HTTP response code.

200 - OK / success.

400 - Bad Request. Returned typically if mandatory parameters are missing or contains invalid data.

429 - Too Many Requests.
ip (data)
Object
ip
IP address, e.g. "66.220.144.0". Either specified in ip parameter or detected by the system.
city
City of IP address, e.g. "Menlo Park".
postal
Postal code of IP address, e.g. "94025".
state
State of IP address, e.g. "California".
state_code
State code of IP address, e.g. "CA".
country
Country of IP address, e.g. "United States".
country_code
Country code of IP address, e.g. "US".
location
Geolocation (latitude, longitude) of IP address, e.g. "37.459,-122.1781".
timezone
Object
id
Id of time zone (TZID), e.g. "America/Los_Angeles".
location
Geolocation (latitude, longitude) of time zone city, e.g. "34.05222,-118.24278" which is the geolocation of "Los Angeles".
country_code
Country code of time zone, e.g. "US".
country_name
Country name (official English name) of time zone, e.g. "United States of America".
iso3166_1_alpha_2
Alpha-2 codes from ISO 3166-1, e.g. "US".
iso3166_1_alpha_3
Alpha-3 codes from ISO 3166-1 (synonymous with World Bank Codes), e.g. "USA".
un_m49_code
UN Statistics M49 numeric codes (nearly synonymous with ISO 3166-1 numeric codes, which are based on UN M49., e.g. "840".
itu
Codes assigned by the International Telecommunications Union, e.g. "USA".
marc
MAchine-Readable Cataloging codes from the Library of Congress, e.g. "xxu".
wmo
Country abbreviations by the World Meteorological Organization, e.g. "US".
ds
Distinguishing signs of vehicles in international traffic, e.g. "USA".
phone_prefix
Country code from ITU-T recommendation E.164, sometimes followed by area code, e.g. "1". Can contain multiple values seperated by comma.
fifa
Codes assigned by the Fédération Internationale de Football Association, e.g. "USA".
fips
Codes from the U.S. standard FIPS PUB 10-4, e.g. "US".
gaul
Global Administrative Unit Layers from the Food and Agriculture Organization, e.g. "259".
ioc
Codes assigned by the International Olympics Committee, e.g. "259".
currency_alpha_code
ISO 4217 currency alphabetic code, e.g. "USD".
currency_country_name
ISO 4217 country name, e.g. "UNITED STATES".
currency_minor_unit
ISO 4217 currency number of minor units, e.g. "2".
currency_name
ISO 4217 currency name, e.g. "US Dollar".
currency_code
ISO 4217 currency numeric code, e.g. "840".
independent
Country status, based on the CIA World Factbook, e.g. "Yes".
capital
Capital city from Geonames, e.g. "Washington".
continent
Continent from Geonames, e.g. "NA".
tld
Top level domain from Geonames, e.g. ".us".
languages
Languages from Geonames, e.g. "en-US,es-US,haw,fr".
geoname_id
Geoname id, e.g. "6252001".
edgar
EDGAR country code from SEC, e.g. "G7".
datetime
Object
date
Date presented in the format (MM/DD/YYYY), e.g. "12/05/2024".
date_time
Date / time presented in the format (MM/DD/YYYY HH:II:SS), e.g. "12/05/2024 01:35:13".
date_time_txt
Textual presentation of date / time, e.g. "Monday, December 5, 2024 01:35:13".
date_time_wti
RFC 2822 formatted date, e.g. "Mon, 05 Dec 2024 01:35:13 -0800".
date_time_ymd
ISO 8601 date, e.g. "2024-12-05T01:35:13-08:00".
time
Time presented in the format (HH:II:SS), e.g. "01:35:13".
month
1 through 12 - Numeric representation of a month, without leading zeros
month_wilz
01 through 12 - Numeric representation of a month, with leading zeros
month_abbr
Jan through Dec - A short textual representation of a month, three letters
month_full
January through December - A full textual representation of a month, such as January or March
month_days
28 through 31 - Number of days in the given month
day
1 to 31 - Day of the month without leading zeros
day_wilz
01 to 31 - Day of the month, 2 digits with leading zeros
day_abbr
Mon through Sun - A textual representation of a day, three letters
day_full
Sunday through Saturday - A full textual representation of the day of the week
year
Examples: 1999 or 2003 - A full numeric representation of a year, 4 digits
year_abbr
Examples: 99 or 03 - A two digit representation of a year
hour_12_wolz
1 through 12 - 12-hour format of an hour without leading zeros
hour_12_wilz
01 through 12 - 12-hour format of an hour with leading zeros
hour_24_wolz
0 through 23 - 24-hour format of an hour without leading zeros
hour_24_wilz
00 through 23 - 24-hour format of an hour with leading zeros
hour_am_pm
am or pm - Lowercase Ante meridiem and Post meridiem
minutes
00 to 59 - Minutes with leading zeros
seconds
00 through 59 - Seconds, with leading zeros
week
Example: 42 (the 42nd week in the year)
offset_seconds
-43200 through 50400 - Timezone offset in seconds. The offset for timezones west of UTC is always negative, and for those east of UTC is always positive.
offset_minutes
Timezone offset in minutes.
offset_hours
Timezone offset in hours.
offset_gmt
Example: +02:00 - Difference to Greenwich time (GMT) with colon between hours and minutes
offset_tzid
Examples: UTC, GMT, Atlantic/Azores - Timezone identifier
offset_tzab
Examples: EST, MDT ... - Timezone abbreviation
offset_tzfull
Examples: Full name of date/time abbreviation, e.g. full name of CET is "Central European Time".
dst
Whether the date is in Daylight Savings Time? Returns "true" or "false".
dst_observes
Whether the time zone observe Daylight Savings Time? Returns "true" or "false".
tz_string
POSIX-style TZ string.
timeday_spe
Specific time of day.

05am - 08am = early_morning (morning)
08am - 10am = morning (morning)
10am - 12pm = late_morning (morning)
12pm - 03pm = early_afternoon (afternoon)
03pm - 05pm = late_afternoon (afternoon)
05pm - 07pm = early_evening (evening)
07pm - 09pm = evening (evening)
09pm - 12pm = night (night)
00am - 05am = late_night (night)
timeday_gen
General time of day. Values can be: morning, afternoon, evening, night

Testing 1, 2, 3.. Sign up when you're ready!

We've made it easy for you to test out our API's. Simply click the "Token" link on each API page and a temporary token is generated instantly. You can generate up to five test tokens. Each token is valid for 20 requests. When you're ready to put the code into production then sign up for a plan to get a service token.

Service Token  (for testing)

A test token has been generated for you. It's good for 20 requests. Please notice: When using a test token the request reponse time is reduced drastically.

TOKEN Copied note_add