API Services - Telephone Lookup
Look up information on a telephone number. The API will return detailed information.
URL
https://api.proxstop.com/telephonelookup.format
Formats
json, xml
HTTP Methods
GET, POST
Request Data
Required |
Variable |
Example |
Info |
Yes |
key |
098f6bcd4621d373cade4e832627b4f6 |
Your unique API key |
No |
country |
1 |
Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1]. Click here for a list of country phone codes. |
Yes |
phone |
5555555555 |
Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc. |
Example Request
https://api.proxstop.com/telephonelookup.xml?key=098f6bcd4621d373cade4e832627b4f6&country=1&phone=5555555555
Response Data
Variable |
Example |
Info |
countrycode |
1 |
One to three-digit country code associated with the country of the phone number passed to the PhoneLookup API. Should be the same country code passed to ProxStop's API during the PhoneLookup request. |
ophone |
5555555555 |
The original phone number passed to ProxStop's PhoneLookup API. Numeric string. |
cphone |
5555555555 |
If the phone number was entered in an incorrect format (i.e. the phone number included 00, 011, or the country code was entered twice), the cleansed phone number is returned in this parameter. Numeric string. |
ccode |
0 |
One of the Cleansing Codes describing the cleansing operation performed on the phone number. The default value is 100 (No changes were made to the phone number). |
city |
New York |
A string specifying the name of the city associated with the phone number. |
state |
NY |
The 2-letter State Abbreviation Code of the state (province, district, or territory) associated with the phone number (North America only). |
zip |
10075 |
The 5-digit United States Postal Service ZIP Code associated with the phone number (U.S. only). |
county |
|
A string specifying the name of the County (or Parish) associated with the phone number (U.S. only). |
country |
US |
Two-letter ISO country code associated with phone number. |
countryname |
United States |
Full country name associated with the phone number. |
timezone |
America/New_York |
Descriptive time zone associated with phone number. |
utcmin |
-5 |
In the US, the Universal Time of the phone number entered is returned. Internationally, the minimum Universal time for the country associated with the phone number entered is returned. Number that ranges from -12 to +12. |
utcmax |
-5 |
In the US, utcmax returns the same information as utcmin. Internationally, the maximum Universal time for the country associated with the phone number entered is returned. |
lat |
42.59390 |
Latitude associated with phone number. |
lon |
-82.87835 |
Longitude associated with phone number. |
min |
10 |
Minimum phone number length of telephone numbers with the country code/area code combination of phone number. |
max |
10 |
Maximum phone number length of telephone numbers with the country code/area code combination of phone number. |
type |
302 |
Code indicating type of phone associated with phone number. Click here for a list of telephone types. |
carrier |
Verizon Wireless |
A string specifying the name of the carrier. |
Good Response Example
<?xml version="1.0" encoding="UTF-8"?>
<response>
<countrycode>1</countrycode>
<ophone>5555555555</ophone>
<cphone>5555555555</cphone>
<ccode>0</ccode>
<city>New York</city>
<state>NY</state>
<zip>10075</zip>
<county></county>
<country>US</country>
<countryname>United States</countryname>
<timezone>America/New_York</timezone>
<utcmin>-5</utcmin>
<utcmax>-5</utcmax>
<lat>42.59390</lat>
<lon>-82.87835</lon>
<min>10</min>
<max>10</max>
<type>302</type>
<carrier>Verizon Wireless</carrier>
</response>
{
"version": "1.0",
"encoding": "UTF-8",
"response": {
"countrycode": 1
"ophone": 5555555555
"cphone": 5555555555
"ccode": 0
"city": New York
"state": NY
"zip": 10075
"county":
"country": US
"countryname": United States
"timezone": America/New_York
"utcmin": -5
"utcmax": -5
"lat": 42.59390
"lon": -82.87835
"min": 10
"max": 10
"type": 302
"carrier": Verizon Wireless
}
}
Bad Response Example
<?xml version="1.0" encoding="UTF-8"?>
<failed>
<error_code>INVALID_TELEPHONE</error_code>
<error_msg>The telephone number provided is not valid.</error_msg>
</failed>
{
"version": "1.0",
"encoding": "UTF-8",
"failed": {
"error_code": "INVALID_TELEPHONE",
"error_msg": "The telephone number provided is not valid."
}
}
Simple Programming Example
This uses our PHP5 class which can be downloaded by
clicking here. The downloadable zip archive will also contain more detailed examples with forms.
// Load config & main class
require_once('config.ProxStop.php');
// Perform Lookup
$country = '1'; // Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].
$phone = '5555555555'; // Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.
$result = $ProxStop->telephoneLookup($country,$phone);
// The lookup failed, print the error message.
if($result===false)
{
echo 'The lookup failed with the error "'.$ProxStop->errors['code'].': '.$ProxStop->errors['msg'].'"';
}
// The lookup was good
else
{
echo 'Below are some details on the phone number:<br />';
echo 'City: '.$result->city.'<br />';
echo 'State: '.$result->state.'<br />';
echo 'Zip: '.$result->zip;
// Review the documentation for showing more information
}
$apiUrl = 'https://api.proxstop.com/telephonelookup.xml';
$apiKey = '098f6bcd4621d373cade4e832627b4f6'; // Replace with your API key
$country = '1'; // Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].
$phone = '5555555555'; // Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.
$result = file_get_contents($apiUrl.'?key='.$apiKey.'&country='.$country.'&phone='.$phone);
$result = simplexml_load_string($result);
if(isset($result->error_code))
{
echo 'The lookup failed with the error "'.$result->error_code.': '.$result->error_msg.'"';
}
else if(!isset($result->countrycode))
{
echo 'The service seems to be temporarily unavailable.';
}
else
{
// Do what you need here
}
string apiUrl = "https://api.proxstop.com/telephonelookup.xml";
string apiKey = "098f6bcd4621d373cade4e832627b4f6"; // Replace with your API key
string varCountry = "1"; // Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].
string varPhone = "5555555555"; // Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.
string results = new System.Net.WebClient().DownloadString(apiUrl+"?key="+apiKey+"&country="+varCountry+"&phone="+varPhone);
System.Xml.XmlDocument doc = new System.Xml.XmlDocument();
doc.LoadXml(results);
if(doc.SelectSingleNode("//failed/error_code")!=null)
{
Response.Write("The lookup failed with the error \""+doc.SelectSingleNode("//failed/error_code/text()").Value+": "+doc.SelectSingleNode("//failed/error_msg/text()").Value+"\"");
}
else if(doc.SelectSingleNode("//response/countrycode")==null)
{
Response.Write("The service seems to be temporarily unavailable.");
}
else
{
// Do what you need here
}
require 'net/http'
require 'rexml/document'
apiUrl = 'https://api.proxstop.com/telephonelookup.xml'
apiKey = '098f6bcd4621d373cade4e832627b4f6' #Replace with your API key
country = '1' #Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].
phone = '5555555555' #Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.
xml_data = Net::HTTP.get_response(URI.parse(apiUrl+'?key='+apiKey+'&country='+country+'&phone='+phone)).body
doc = REXML::Document.new(xml_data)
if doc.elements['failed/error_code']
print 'The lookup failed with the error '+doc.elements['failed/error_code'].text+': '+doc.elements['failed/error_msg'].text
elsif !doc.elements['response/countrycode']
print 'The service seems to be temporarily unavailable.'
else
#Do what you need here
end
from urllib.request import urlopen
from xml.dom import minidom
apiUrl = 'https://api.proxstop.com/telephonelookup.xml'
apiKey = '098f6bcd4621d373cade4e832627b4f6' #Replace with your API key
country = '1' #Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].
phone = '5555555555' #Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.
dom = minidom.parse(urlopen(apiUrl+'?key='+apiKey+'&country='+country+'&phone='+phone))
if (dom.getElementsByTagName('error_code')):
print (dom.getElementsByTagName('error_code')[0].firstChild.data+': '+dom.getElementsByTagName('error_msg')[0].firstChild.data)
elif not (dom.getElementsByTagName('response')):
print ('The service seems to be temporarily unavailable.')
else:
#Do what you need here
print ('Success')
const http = require('http');
var apiHost = 'api.proxstop.com';
var apiPath = '/telephonelookup.json';
var apiKey = '098f6bcd4621d373cade4e832627b4f6'; //Replace with your API key
var varCountry = '1'; //Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].
var varPhone = '5555555555'; //Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.
http.get({host:apiHost,port:80,path:apiPath+'?key='+apiKey+'&country='+varCountry+'&phone='+varPhone,agent:false},function(res){
res.setEncoding('utf8');
res.on('data',function(chunk){
var json = JSON.parse(chunk);
if(json.failed!=undefined) {
console.log(json.failed.error_code+': '+json.failed.error_msg);
} else if(json.response==undefined) {
console.log('The service seems to be temporarily unavailable.');
} else {
//Do what you need here
console.log('Success');
}
});
});
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.DocumentBuilder;
import org.w3c.dom.Document;
import org.w3c.dom.*;
import org.xml.sax.SAXException;
import org.xml.sax.SAXParseException;
import java.io.File;
public class ProxStop {
public static void main(String[] args) {
String apiUrl = "https://api.proxstop.com/telephonelookup.xml";
String apiKey = "098f6bcd4621d373cade4e832627b4f6"; //Replace with your API key
String varCountry = "1"; //Country code associated with the phone number that is being identified. 1 to 3 digits; do not include 00 or 011 [default: 1].
String varPhone = "5555555555"; //Phone number, including area code, to be identified. Numeric only; remove spaces, hyphens, parenthesis, etc.
try {
DocumentBuilderFactory dbFactory = DocumentBuilderFactory.newInstance();
DocumentBuilder dBuilder = dbFactory.newDocumentBuilder();
Element docEle = dBuilder.parse(apiUrl+"?key="+apiKey+"&country="+varCountry+"&phone="+varPhone).getDocumentElement();
if (docEle.getNodeName()=="failed") {
System.out.println(docEle.getElementsByTagName("error_code").item(0).getChildNodes().item(0).getNodeValue()+": "+docEle.getElementsByTagName("error_msg").item(0).getChildNodes().item(0).getNodeValue());
} else if (docEle.getNodeName()!="response") {
System.out.println("The service seems to be temporarily unavailable.");
} else {
//Do what you need here
System.out.println("Success.");
}
} catch (SAXParseException err) {
} catch (SAXException e) {
} catch (Throwable t) {
}
}
}
Price
Please login to your account and navigate to the API page to view pricing.