Address

The address API enables you to request an address and get the details about the address in return. Be specific with your address parameters as the request can return multiple results.

Data
Please URL encode all parameter values.

NOTICE
Searching for an address is a complex operation. The request can take up to several hundred miliseconds. We recommend using the address API asynchronously.

Get an address, time zone and date/time details

Returns address, timezone and datetime information. Please notice: The request can return multiple results. Be specific when requesting an address if you intent only to have one result returned. Date/time defaults to when the request was made. 

$ curl https://timezoneapi.io/api/address/?Hacker+Way+1+Menlo+Park+California&token=TOKEN

// Get JSON object
$jsondata = file_get_contents("https://timezoneapi.io/api/address/?Hacker+Way+1+Menlo+Park+California&token=TOKEN");

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

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

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

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

}

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

// Request
request('https://timezoneapi.io/api/address/?Hacker+Way+1+Menlo+Park+California&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.addresses[0].city;

        // Example: Get the users time
        var time = data.data.addresses[0].datetime.date_time_txt;

    }

});

// Get JSON object
$.getJSON('https://timezoneapi.io/api/address/?Hacker+Way+1+Menlo+Park+California&token=TOKEN', function(data){

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

		// Log
		console.log(data);

		// Example: Get the city parameter
		var city = data.data.addresses[0].city;
		alert(city);

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

	}

});

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

# Get JSON and parse
data = JSON.parse(open('https://timezoneapi.io/api/address/?Hacker+Way+1+Menlo+Park+California&token=TOKEN').read)

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

# Import
import requests

# Get
response = requests.get('https://timezoneapi.io/api/address/?Hacker+Way+1+Menlo+Park+California&token=TOKEN')

# Parse JSON
data = response.json()

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

Returns

{
	"meta": {
		"code": "200"
	},
	"data": {
		"addresses_found": "1",
		"addresses": [{
			"street": "Hacker Way",
			"street_abbr": "Hacker Way",
			"street_number": "1",
			"street_subpremise": null,
			"postal_code": "94025",
			"postal_code_suffix": "1456",
			"city": "Menlo Park",
			"county": "San Mateo County",
			"state": "California",
			"state_code": "CA",
			"country": "United States",
			"country_code": "US",
			"formatted_address": "1 Hacker Way, Menlo Park, CA 94025, USA",
			"location": "37.4846262,-122.1478991",
			"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\/11\/2023",
				"date_time": "12\/11\/2023 03:45:24",
				"date_time_txt": "Sunday, December 11, 2023 03:45:24",
				"date_time_wti": "Sun, 11 Dec 2023 03:45:24 -0800",
				"date_time_ymd": "2023-12-11T03:45:24-08:00",
				"time": "03:45:24",
				"month": "12",
				"month_wilz": "12",
				"month_abbr": "Dec",
				"month_full": "December",
				"month_days": "31",
				"day": "11",
				"day_wilz": "11",
				"day_abbr": "Sun",
				"day_full": "Sunday",
				"year": "2023",
				"year_abbr": "16",
				"hour_12_wolz": "3",
				"hour_12_wilz": "03",
				"hour_24_wolz": "3",
				"hour_24_wilz": "03",
				"hour_am_pm": "am",
				"minutes": "45",
				"seconds": "24",
				"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/address/?token=12345678
address
Mandatory.

https://timezoneapi.io/api/address/?Hacker+Way+1+Menlo+Park+California

or

https://timezoneapi.io/api/address/?address=Hacker+Way+1+Menlo+Park+California
date
Optional.

https://timezoneapi.io/api/address/?Hacker+Way+1+Menlo+Park+California&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/address/?address=Hacker+Way+1+Menlo+Park+California&output=text
only
Optional.

Lets you choose which fields to output. In below example we only need to output address country and children from the timezone object.

Example: /?only=address,country,timezone(location,country_name)

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.
address (data)
Object
addresses_found
The number of addresses found by the system.
addresses
Array of addresses
street
Street name of the address, e.g. "Second Avenue".
street_abbr
Street name (short) of the address, e.g. "2nd Ave".
street_number
Street number of the address, e.g. "1".
street_subpremise
Street subpremise of the address, e.g. "500". Could be suite, apartment number etc.
postal_code
Postal code of the address, e.g. "94025".
postal_code_suffix
Postal code suffix of the address, e.g. "1456".
city
City of the address, e.g. "Menlo Park".
county
County of the address, e.g. "San Mateo".
state
State of the address, e.g. "California".
state_code
State code of the address, e.g. "CA".
country
Country of the address, e.g. "United States".
country_code
Country code of the address, e.g. "US".
formatted_address
The address returned formatted.
location
Geolocation (latitude, longitude) of 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/2023".
date_time
Date / time presented in the format (MM/DD/YYYY HH:II:SS), e.g. "12/05/2023 01:35:13".
date_time_txt
Textual presentation of date / time, e.g. "Monday, December 5, 2023 01:35:13".
date_time_wti
RFC 2822 formatted date, e.g. "Mon, 05 Dec 2023 01:35:13 -0800".
date_time_ymd
ISO 8601 date, e.g. "2023-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

© TimezoneAPI, All rights reserved.