Free Phone Number Lookup and Validation API

The API base path is

http://phone-number-api.com/xml/?number={number}

Parameters

{number} is the phone number.

http://phone-number-api.com/xml/?number={number}&fields=117443071

fields	response fields optional
dial_from	two-letter country code ISO 3166-1 alpha-2 where you want to dial the number from optional
lang	response language optional

There is no API key required.

Quick test

You can edit this query and play around with the options

Response

Returned data

The API can return the following fields and values

If you don't require all the returned fields, use the GET parameter fields to specify which data should be returned. Separate the fields by comma (fields=status,message,query,country,city) or use a generated, numeric value (to save bandwidth)

name	description	example	type
status	success or fail	success	string
message	Included only when status is fail Can be one of the following: invalid country, too short, too long, invalid query	invalid query	string
numberType	Can be one of the following: fixed, mobile, fixed or mobile, toll free, premium, voip , pager, personal number, shard cost, uan, voicemail, unkown, invalid query	mobile	string
numberValid	Validity of phone number	true	bool
numberValidForRegion	Validity of phone number for that region	true	bool
numberCountryCode	Phone country code	1	number
numberAreaCode	phone area code	252	number
formatE164	Phone number in E.165 format	+12524589668	string
formatNational	Phone number in national format	(213) 765-1000	string
formatInternational	Phone number in national format	+1 213-765-1000	string
dialFromCountryCode	Country code you want to dial from (callback dial_from)	FR	string
dialFromCountryNumber	Phone number to dial from dial_from parameter (default: US)	00 1 213-765-1000	string
ext	Extension, entered via ext., x or url encoded # (%23)	485	string
carrier	Carrier name	Vodafone	string
continent	Continent name	North America	string
continentCode	Two-letter continent code	NA	string
countryName	Country name	United States	string
country	Two-letter country code ISO 3166-1 alpha-2	US	string
region	Region/state short code (FIPS or ISO)	CA or 10	string
regionName	Region/state	California	string
city	City	Los Angeles	string
zip	Zip code	94043	string
lat	Latitude	37.4192	float
lon	Longitude	-122.0574	float
timezone	Timezone (tz)	America/Los_Angeles	string
offset	Timezone UTC DST offset in seconds	-25200	int
currency	National currency	USD	string
query	Phone number used for the query	12134635888	string

Response

status,message,numberType,numberValid,formatE164,countryName,country,region,regionName,city,zip,lat,lon,timezone,query

http://phone-number-api.com/xml/?number={number}&fields=status,message,numberType,numberValid,formatE164,countryName,country,region,regionName,city,zip,lat,lon,timezone,query

Response

117443071

http://phone-number-api.com/xml/?number={number}&fields=117443071

Localization

Localized city, regionName and country can be requested by setting the GET parameter lang to one of the following:

lang (ISO 639)	description
en	English (default)
de	Deutsch (German)
es	Español (Spanish)
pt	Português - Brasil (Portuguese)
fr	Français (French)
ja	日本語 (Japanese)
zh	中国 (Chinese)
ru	Русский (Russian)

SSL (HTTPS)

256-bit SSL encryption is not available for this free API. Please see our pro service.

Usage limits

This endpoint is limited to 5 requests per minute from an IP address.

If you go over the limit your requests will be throttled (HTTP 429) until your rate limit is reset. If you constantly go over the limit your IP address will be banned for one hour.

The returned HTTP header X-Rl contains the number of requests remaining in the current rate limit window.

Your implementation should always check the value of the X-Rl header, and if the value is 0, you must not send any more requests for the next 60 seconds.

We do not allow commercial use for this endpoint. Please see our pro service for SSL access, unlimited queries and commercial support.