The API base path is

Parameters

{number} is the phone number.

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)

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

117443071

Localization

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

Callback (JSONP)

By default there is no callback function called, but you can supply your own with the GET parameter callback

Example: http://phone-number-api.com/json/?number={number}&callback={callback}

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.

JavaScript code example

// An example script to validate the entered phone number
// in order to send a SMS or initiate an outbound call to the user

// we need only the the parameters numberType, numberValid and formatE164, of course you can request more fields
// see https://phone-number-api.com/docs/api:json for documentation
var phone_number = document.getElementById("phone_number").value;
var endpoint = 'http://phone-number-api.com/json/?number='+phone_number+'&fields=status,message,numberType,numberValid';

var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
	if (this.readyState == 4 && this.status == 200) {
		var response = JSON.parse(this.responseText);
		if(response.status !== 'success') {
			console.log('query failed: ' + response.message);
			return
		}
		// Actions
		if(response.numberValid == true) {		
			if(response.numberType == "MOBILE") {				
				console.log('send SMS from the backend to ' + response.formatE164);
			}else{				
				console.log('initiate outbound call from the backend to ' + response.formatE164);
			}
		}else{
			console.log('re-enter number...');				
		}
	}
};
xhr.open('GET', endpoint, true);
xhr.send();

// An example script for finding out the distance from the user to multiple points

// Coordinates and name
var coords = [	
	{lat: 51.509865, lon: -0.136439, name: 'London, United Kingdom'},
	{lat: 52.520008, lon: 13.381777, name: 'Berlin, Germany'},	
	{lat: 40.7127837, lon: -74.0059413, name: 'New York, NY'},		
	{lat: 41.8781136, lon: -87.6297982, name: 'Chicago, IL'},	
	{lat: 37.3382082, lon: -121.8863286, name: 'San Jose, CA'},
	{lat: 34.0522342, lon: -118.2436849, name: 'Los Angeles, CA'},
	];

// phone-number-api endpoint URL
// see https://phone-number-api.com/docs/api:json for documentation
var phone_number = document.getElementById("phone_number").value;
var endpoint = 'http://phone-number-api.com/json/?number='+phone_number+'&fields=status,message,lat,lon,numberValid';

function getDistanceFromLatLonInKm(lat1, lon1, lat2, lon2) {
	var R = 6371; // Radius of the earth in km
	var dLat = deg2rad(lat2-lat1);  // deg2rad below
	var dLon = deg2rad(lon2-lon1); 
	var a = Math.sin(dLat/2) * Math.sin(dLat/2) +
		Math.cos(deg2rad(lat1)) * Math.cos(deg2rad(lat2)) * 
		Math.sin(dLon/2) * Math.sin(dLon/2); 
	var c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1-a)); 
	var d = R * c; // Distance in km
	return d;
}

function deg2rad(deg) {
	return deg * (Math.PI/180)
}

var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function() {
	if(this.readyState == 4 && this.status == 200) {
		var response = JSON.parse(this.responseText);
		if(response.status !== 'success') {
			console.log('query failed: ' + response.message);
			return
		}
		// Distance in kilometers for each coordinate		
		if(response.numberValid == 'true') {
			for(var i = 0; i < coords.length; i++) {
				var diff = getDistanceFromLatLonInKm(coords[i].lat, coords[i].lon, response.lat, response.lon);
				console.log('distance to ' + coords[i].name + ': ' + diff + 'km');
			}
		}else{
			console.log('re-enter number...');
		}		
	}
};
xhr.open('GET', endpoint, true);
xhr.send();