This document defines the input, output and behavior of the web service operations in GeoPhone. Each operation has its own unique behavior and output, although all of the operations are very similar.
 
Important Note!
Reverse-phone lookups are subject to federal rules determining who can procure data, and for what purpose. Currently, both disconnected and unlisted numbers return no contact information, and there are no public datasets regarding wireless numbers. GeoPhone returns contact information for connected landline phone numbers. Even in the cases that the phone number is disconnected or wireless, GeoPhone will commonly return the exchange information.
GeoPhone can provide information regarding Canadian phone numbers, although GeoPhone’s Canadian data is not as comprehensive as its US information. You should examine your own business needs first before exploring what GeoPhone can provide. Different operations may be necessary based on the information you have, and the granularity of data you need.
 
This is an improved version of the basic GetPhoneInfo operation. Given a phone number, will consult national directory-assistance databases to find the owner and address registered. The addresses returned are not validated via any address-validation technique. They are returned to you exactly as the phone carrier releases them. If you need these addresses to be validated, using Service Objects’ AddressValidation web services is highly recommended. 

 

Both the contact’s information and the phone company’s information are returned with this operation. The other operations in this service return the same data, but pared down.
 
Two valuable bits of information are also retrieved – whether the phone line is for business or residential purposes, and whether the phone line is landline, wireless or voip. Unique to this operation, latitude and longitude are returned. Coordinates are city centroids (ie the center points of the city the number is found in), but in most cases this is tied to a smaller area (for example, it’s the center of a suburb of a bigger city).

 

Finally, also new is the quality field. Currently all contacts will be returned as HIGH quality. Current contact data is updated daily and is very accurate. We may add additional data sources in the future that would supplement these results. These additional sources may not be as “fresh” or reliable as our current ones and would be given lower quality ratings. By examining the WSDL, you may see that multiple groups of contact/exchange information are possible. Although they are possible in the XML, you will only see one exchange per output, always. It is common, however, to see multiple contacts per phone number (as people change numbers, or there may be multiple businesses at the same phone number.) It is highly recommended that you handle each of these contacts, rather than just the first contact returned.
 

URL Endpoints

GetPhoneInfo_V2 Input

Name Type Description
PhoneNumber String Phone number to look up, for example, “805-963-1700”
LicenseKey String Your license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/phone-insight/

GetPhoneInfo_V2 Outputs

Name Type Description
Providers Providers[] Contains the results for the Provider Object
Contacts Contacts[] An array of contacts associated with the given phone numbers
Error Error Error Object Indicating why the service could not return a
result
  • Providers Output
Name Type Values Description
Name String Varies The name of the line carrier
of the phone number
(“AT&T”).
City String Varies The city location of the
carrier’s exchange (“New
York”).
State String Varies The state location of the
carrier’s exchange (“NY”)
LineType [1] String LANDLINE,
WIRELESS,
UNKNOWN,
VOIP		 The type of the phone line,
can either be “Landline” or
“Wireless” or “VOIP” or
“Unknown”.
Latitude String Varies The latitude coordinate for
the phone number.
Longitude String Varies The longitude coordinate for
the phone number.
Quality String HIGH,
MEDIUM,
LOW		 This field is not currently
used as all data sources are
considered high quality. In
the future there may be
“other” sources that may not
be as reliable.
  • Contacts Output
Name Type Values Description
Name String Varies The name that the phone line is registered to. Can either be a person (“John Doe”) or a business (“Doe Corporation”).
Address String Varies The street address to which the phone line is registered.
City String Varies The city to which the phone line is registered.
State String Varies The state to which the phone line is registered.
Zip String Varies The zip code to which the phone line is registered.
Type String RESIDENTIAL, BUSINESS, UNKNOWN The type of entity that owns the phone line, will be either “Residential” or “Business”.

References

  1. ^ Reverse Phone Lookup APIs – Differences Between GeoPhone & GeoPhone Plus