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”. |