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

NameTypeDescription
PhoneNumberStringPhone number to look up, for example, “805-963-1700”
LicenseKeyStringYour license key to use the service.
Sign up for a free trial key at
https://www.serviceobjects.com/products/phone/geophone

GetPhoneInfo_V2 Outputs

NameTypeDescription
ProvidersObjectContains the results for the Provider Object
ContactsContacts[]An array of contacts associated with the given phone numbers
ErrorError Error Object Indicating why the service could not return a
result
NameTypeValuesDescription
NameStringVariesThe name of the line carrier
of the phone number
(“AT&T”).
CityStringVariesThe city location of the
carrier’s exchange (“New
York”).
StateStringVariesThe state location of the
carrier’s exchange (“NY”)
LineType [1]StringLANDLINE,
WIRELESS,
UNKNOWN,
VOIP
The type of the phone line,
can either be “Landline” or
“Wireless” or “VOIP” or
“Unknown”.
LatitudeStringVariesThe latitude coordinate for
the phone number.
LongitudeStringVariesThe longitude coordinate for
the phone number.
QualityStringHIGH,
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.
NameTypeValuesDescription
NameStringVariesThe name that the phone line is registered to. Can either be a person (“John Doe”) or a business (“Doe Corporation”).
AddressStringVariesThe street address to which the phone line is registered.
CityStringVariesThe city to which the phone line is registered.
StateStringVariesThe state to which the phone line is registered.
ZipStringVariesThe zip code to which the phone line is registered.
TypeStringRESIDENTIAL, BUSINESS, UNKNOWNThe 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