Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migrated to Confluence 5.3

Table of Contents
maxLevel2

Introduction

DOTS GeoPhone Plus (referred to as "GeoPhone Plus" or "GPPL") is a publicly available XML web service that provides reverse phone lookup information about a US (or sometimes Canadian) phone number. The service provides name, address, city and state, along with carrier exchange information.

This is a composite service that combines the datasets from our DOTS GeoPhone and DOTS GeoPhone Wireless services to provide the most comprehensive contact data possible. Landline, wireless and tollfree contact data are all available with one call to the service. GeoPhone Plus can provide instant reverse-phone lookup verification to websites or data enhancement to contact lists. However, the output from GP must be considered carefully before the existence or non-existence of a given phone number is decided.

Integration

Integrating GPPL into your application should be easy and straightforward. If you are using a common platform, ServiceObjects may already have sample code built that you can use:
http://www.serviceobjects.com/developers/sample-code/geophone

However, if you are using a common platform that does not already have sample code, you can ask ServiceObjects to build you an example. Email support@serviceobjects.com for more details.

Web Service Structure

Web services are methods that integrate with other applications via the web, and encapsulate tricky business logic. Web services are too large of a topic to cover in this document, but ServiceObjects has developed its web services to be as easy to integrate and as accessible as possible.
GeoPhone Plus is a public XML web service that supports SOAP, POST and GET operations.

The host path, or physical location of the web service is here:
http://trial.serviceobjects.com/gppl/GeoPhonePlus.asmx

The location of the WSDL, or Web Service Definition Language document, is here (This is also accessible via the "Service Definition" link.):
http://trial.serviceobjects.com/gppl/GeoPhonePlus.asmx?WSDL

Note

Important Note!
SOAP is done via POST, only with special XML markup in the post-body.

This WSDL is the definition of the web service, meaning its inputs, outputs, operations, and the like. Most likely, you will have another tool read this WSDL and make the operations available to you in your application. Whenever your utilities or IDE asks for a WSDL path to GeoPhone Plus, you can provide this one. Every web service has operations that it offers to subscribers – methods that do different work and return different output. Currently GeoPhone Plus has two operations:

GetPhoneInfo – returns the reverse-phone lookup information about any given phone number, including the name, address, city and state (contact information) and the carrier name, city, state and line type (exchange information).(Deprecated: Use GetPhoneInfo_V2)
GetPhoneInfo_V2 – returns the same reverse-phone lookup information that GetPhoneInfo does with a few notable additions. A connection status and recommendation is added. Also, a new enhanced data source is added that supplements the existing sources. (Recommended operation)
This operation will be described in more detail below...

Each of these operations will be described in detail later in this document.

Request Types

GPPL is a public XML web service that supports SOAP(1.1 and 1.2), POST and GET request methods. A request type is just the type of web (HTTP) request to interact with our web services.
GET - All of the input data is in the query string appended to the url. The response is simple XML.
POST - The input parameters are in the body of the request instead of the query string. The response is simple XML.
SOAP - The input parameters are in and XML SOAP message contained in the body of the request. The response is an XML SOAP message.

Analysis of Request Types

GET is the easiest method to implement by hand because all you have to do is set up the URL and query string. It is also easy to debug because you can test the URL + query string in a web browser and see the output.
POST is probably the best method to implement by hand because you do not have to know the specifics of SOAP, and is a little cleaner than passing input parameters in the query string via GET.
SOAP is the best method if you are using a platform that supports SOAP. In many programming environments you can give your IDE (Integrated Development Environment) the URL to the WSDL of a web service ([http://trial.serviceobjects.com/gppl/GeoPhonePlus.asmx?WSDL|http://trial.serviceobjects.com/gppl/GeoPhonePlus.asmx?WSDL]) and it will create a proxy class to help you interact with the web service. In this case you only have to create an instance of the proxy and use its methods. This completely abstracts the programmer from any complications like sending/receiving web requests/responses as well as any xml parsing.

XML Parsing

If you are not using an environment that creates a proxy class for you to use, then you will have to parse xml. If you do have a proxy, then it uses an xml parser for you. Although xml parsing can be done without a parser, most programming environments provide easy access to several standard ones. We strongly recommend that you take advantage of an xml parser. These parsers may take a few extra minutes to integrate but will give your application an added level of security against improper parsing. Without them it is very difficult, even for skilled programmers to write robust code that can handle all cases of xml input properly. Because we have very consistent xml you could get away without this extra precaution, but we suggest you use an xml parser anyway to ensure your application is of the highest quality.

Test Types

Test type only really matters for token users.  For more information on tokens see Appendix A.  For non-token users just submit "FULL" as the test type.

Every call to DOTS GeoPhone Plus requires a test type. A test type is like a key to a set of instructions for how to process a particular call to GPPL. In the case of GPPL, test types are used to determine which datasets to use. Some datasets are more expensive than others and test types can be used to control costs. New test types can freely be added without affecting the data quality or cost for existing users.

As the service matures, new data sources will be added from time to time. If these sources affect cost, new test types will be added. An example of a potential new data source would be disconnected number look-ups which are currently only available in the DOTS Lead Validation service. This check is more costly than the normal checks and so a special test type would be used to perform it. Currently there are only a few available test types, they are:

FULL: - This type currently returns the full available datasets. Landline, wireless,Toll-free and carrier data are all returned when found.
STANDARD: - This type acts as a normal GeoPhone call and returns landline, Toll-free,and carrier data. It does not check for wireless contacts.
More test types will be configured as demand for them is created. But currently these are the only ones needed.

Operation Definitions

This document defines the input, output and behavior of the web service operations in GeoPhone Plus. Currently there is only one.

Note

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. GeoPhone Plus returns contact information for connected landline phone numbers as well as wireless ones. Even in the cases that the phone number is disconnected or unlisted, GeoPhone Plus will commonly return the exchange information. GeoPhone Plus can provide information regarding Canadian phone numbers, although GeoPhone Plus's Canadian data is not as comprehensive as its US information. You should examine your own business needs first before exploring what GeoPhone Plus can provide.

GetPhoneInfo

This is the basic operation for finding the reverse-lookup information. Given a phone number and test type, it 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 ServiceObjects' AddressValidation web services is highly recommended. Both the contact's information and the phone company's information are returned with this operation.

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 or wireless. 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.

GetPhoneInfo Inputs

Name

Type

Description

PhoneNumber

String

10 digit phone number

TestType

String

"FULL", "STANDARD"

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
www.serviceobjects.com.

GetPhoneInfo Outputs

Name

Type

Values

Description

PhoneNumberIn

String

Varies

The original number.

PhoneNumberClean

String

Varies

The number with all special characters removed.

Name (Provider)

String

Varies

The name of the line carrier of the phone number ("AT&T")

City (Provider)

String

Varies

The city location of the carrier's exchange ("New York")

State (Provider)

String

Varies

The state location of the carrier's exchange ("NY")

LineType (Provider)

String

Landline / Wireless / Unknown

The type of the phone line, can either be "Landline" or "Wireless"

Latitude (Provider)

String

Varies

The latitude of the phone exchange

Longitude (Provider)

String

Varies

The longitude of the phone exchange

Name (Contact)

String

Varies

The name that the phone line is registered to. Can either be a person ("John Doe") or a business ("Doe Corporation")

Address (Contact)

String

Varies

The street address to which the phone line is registered

City (Contact)

String

Varies

The city to which the phone line is registered

State (Contact)

String

Varies

The state to which the phone line is registered

Zip (Contact)

String

Varies

The zip code to which the phone line is registered

Type (Contact)

String

Residential / Business / Unknown

The type of entity that owns the phone line, will be either "Residential" or "Business"

Quality (Contact)

String

HIGH,
MEDIUM,
LOW,
UNKNOWN

Not currently used. Landlines are set to HIGH and wireless numbers are set to UNKNOWN. See FAQ for more information.

TokensUsed

String

Varies

The number of tokens used in a given transaction. See Appendix A for details on tokens.

DEBUG

String

Varies

Shouldn't be seen. For debugging only.

Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

"1", "2", "4"

See "Error Codes" below.

Error – Location

String

Always null

Deprecated, no longer used.

GetPhoneInfo_V2

This operation acts almost identically to the older GetPhoneInfo operation with a few key enhancements. A new data source has been added that supplements/enhances/creates contacts returned by the original operation. This new data source returns name only but adds a large number of accurate contacts (especially wireless ones). This new data set will return more contacts than the previous operation. This is the most complete phone data set available. Also added to this operation are two new outputs. IsConnected returns a flag (TRUE, FALSE or UNKNOWN) as to whether the number is known to be a live connected number. This service does not do actual connection testing, but certain contact types are virtually guaranteed to be connected. RecommendConnectionCheck is a ServiceObjects recommendation (TRUE, FALSE or RISKY) for further testing on a particular number to determine if it is actually connected. Generally true disconnected testing on wireless numbers is unreliable so most wireless numbers are marked as RISKY. ServiceObjects has a few options for working with disconnected numbers and is working on more.

GetPhoneInfo_V2 Inputs

Name

Type

Description

PhoneNumber

String

10 digit phone number

TestType

String

"FULL", "STANDARD"

LicenseKey

String

Your license key to use the service.
Sign up for a free trial key at
www.serviceobjects.com.

GetPhoneInfo_V2 Outputs

Name

Type

Values

Description

PhoneNumberIn

String

Varies

The original number.

PhoneNumberClean

String

Varies

The number with all special characters removed.

Name (Provider)

String

Varies

The name of the line carrier of the phone number ("AT&T")

City (Provider)

String

Varies

The city location of the carrier's exchange ("New York")

State (Provider)

String

Varies

The state location of the carrier's exchange ("NY")

LineType (Provider)

String

Landline / Wireless / Unknown

The type of the phone line, can either be "Landline" or "Wireless"

Latitude (Provider)

String

Varies

The latitude of the phone exchange

Longitude (Provider)

String

Varies

The longitude of the phone exchange

Name (Contact)

String

Varies

The name that the phone line is registered to. Can either be a person ("John Doe") or a business ("Doe Corporation")

Address (Contact)

String

Varies

The street address to which the phone line is registered

City (Contact)

String

Varies

The city to which the phone line is registered

State (Contact)

String

Varies

The state to which the phone line is registered

Zip (Contact)

String

Varies

The zip code to which the phone line is registered

Type (Contact)

String

Residential / Business / Unknown

The type of entity that owns the phone line, will be either "Residential" or "Business"

Quality (Contact)

String

HIGH,
MEDIUM,
LOW,
UNKNOWN

Not currently used. Landlines are set to HIGH and wireless numbers are set to UNKNOWN. See FAQ for more information.

TokensUsed

String

Varies

The number of tokens used in a given transaction. See Appendix A for details on tokens.

IsConnected

String

TRUE / FALSE / UNKNOWN

A flag representing if the connection status of the line is known.

RecommendConnectionCheck

String

TRUE / FALSE / RISKY

A recommendation for further testing to determine the connection status of a line.

DEBUG

String

Varies

Shouldn't be seen. For debugging only.

Error – Desc

String

Varies

If there was an internal web service error, the description will be displayed here.

Error – Number

String

"1", "2", "4"

See "Error Codes" below.

Error – Location

String

Always null

Deprecated, no longer used.

Errors

Anything that happens during a run of DOTS GeoPhone Plus that causes it to be unable to finish its normal processing is an error. If an error occurs, something like the following will be the result instead of the normal output:
Example:

Warning
title*Error!*

  <Type>Authorization</Type>
  <TypeCode>1</TypeCode>
  <Desc>Your license key does not work on this service.</Desc>
  <DescCode>8</DescCode>

There are four error types described below. For DOTS GeoPhone Plus, the first two will be the most common.

Error Types

Type

TypeCode

Billable

Standard for all Gen2 Web Services

Authorization

1

No

Yes

User Input

2

Yes

No

Service Objects Fatal

3

No

Yes

Domain Specific

4

Yes

No

Error type 1: Authorization

These are standard to all Generation 2 DOTS Web Services.

DescCode

Desc

0

Unknown authorization error.

1

Please provide a valid license key for this web service.

2

The daily allowable number of transactions for this license key has been exceeded.

3

The monthly allowable number of transactions for this license key has been exceeded.

4

The total allowable number of transactions for this license key has been exceeded.

5

There are not enough transactions available. Check your daily/monthly transaction limits.

6

This license key has not yet been activated.

7

This license key has expired.

8

Your license key does not work on this service.

Error type 2: User Input

These errors occur as a result of bad input. DOTS GeoPhone Plus requires all three inputs to be present in order for a proper validation to take place.

DescCode

Desc

1

Please input a valid 10 digit phone number.

2

The Test Type submitted is not valid.

3You must input a license key in the LicenseKey field.

 

Error type 3: Service Objects Fatal

The Desc will always be the same and the DescCode has no meaning. This is standard to all Generation 2 DOTS Web Services. This is a rare error that signals either a bug in the DOTS GeoPhone Plus service, or a Network/Connectivity issue.

DescCode

Desc

1

Unhandled error. Please contact Service Objects.

Error type 4: Domain Specific

Domain specific errors represent the normal errors seen in ServiceObjects services. For example, if the user is looking for an address in DOTS Address Validation and the address does not exist, a valid domain specific error is "Address not found."

DescCodeDesc
1Phone Number is not valid.

Frequently Asked Questions

The Sample Code is Giving Strange Errors or is Crashing!

Most likely, the sample code cannot connect to Service Objects. Many environments will not allow you to connect out on port 80, or will clip out XML data from these requests/responses.

The easiest way to check for this is to open a browser on the machine running the sample code. In your browser, navigate to:
http://trial.serviceobjects.com/gppl/GeoPhonePlus.asmx

Then try to run one of the operations with your trial key. If you get a browser error, or get no data back, then the sample code isn't able to connect, either. Contact your systems administrator to resolve why you are not able to connect to Service Objects.

GeoPhone Plus doesn't find any data for my phone number!

If your phone number is unlisted, by law, it cannot find any contact information for your number. Additionally, if your number is for a cellular phone, it cannot find that contact information either. If it does not return any information for the exchange, then you may have mistyped your phone number. A valid phone number will always return exchange information, whether it is wireless or landline, connected or disconnected.

GeoPhone Plus is giving someone else's information for my phone number!

GeoPhone Plus's data is updated constantly. In the case that you just changed your number, it is possible it has not been updated since you made the change. Occasionally phone companies take their time in publishing updates.
If the information is not accurate, and the given phone number has not recently changed ownership, please let us know at support@serviceobjects.com.

Can GeoPhone Plus give me the information for a disconnected number?


No, although we are working on procuring this information. If you are interested in using this data, please contact us at support@serviceobjects.com, and we will let you know when that has been implemented.

Can GeoPhone Plus give me the information for a Canadian phone number?


Yes – normally. Our dataset for Canada isn't as extensive as our dataset for the US, but GeoPhone Plus returns information for Canadian phone numbers.

I'm seeing multiple contacts at a single phone number. Who is really going to pick up the phone?

Honestly, any one of them! Typically, this means that multiple people are registered to that phone number, which happens with many small businesses. Oftentimes, when you call the number, you will get an operator or switch where you can ask for the person you're looking for. If the phone number resolves to a residential address, all of the contacts may be roommates.
If you need to verify that a particular person is at that phone number, simply search for that person in the list of contacts. They are not in any particular order when they are returned.

What does the Quality flag in the contact output mean?

The Quality flag in the contact was designed as a placeholder for identifying lower quality data sets. In the event that Service Objects obtained useful but less reliable phone contact information this flag would be used to identify these new data sources. For now all Landline numbers come back as HIGH Quality and wireless numbers come back as UNKNOWN (due to the current state of wireless data in general). There are no plans to add new lower quality data sources to Geophone Plus at the moment and its likely new data sources would lead to a new operation version or require a special test type to access (eliminating the risk of getting lower quality data by accident).

What are tokens?

See Appendix A for more details on tokens.

I don't care so much about who is at the phone number. I care more about whether the phone number is real or not. What should I do?

You have several options. You can either check for the presence of exchange data (valid phone numbers always return exchange information) or integrate Service Objects' PhoneExchange web service, which was built expressly for this purpose. Find out more about PhoneExchange here: http://www.serviceobjects.com/products/phone/phone-exchange

I'm Not a Programmer. How Do I Use DOTS GeoPhone Plus?

Service Objects runs batches for you! A free batch trial is available at http://www.serviceobjects.com/batch/upload.

Do you also provide a RESTful interface?

Yes we do! For more information on how to use our RESTful interface go here DOTS GeoPhone Plus - REST.

More Information

Appendix A – Tokens: An Advanced Feature

The standard usage and pricing plan for use of DOTS Geophone Plus is based on transactions as the aggregated and charged for unit. Transactions in this context are defined as: any DOTS Geophone Plus procedure call made to Service Objects web service, regardless of returned information or use of returned information. There is an advanced feature of DOTS Geophone Plus for more sophisticated users called Tokens. A Token is a unit of cost where different results are weighted differently resulting in a variable cost per transaction type. Transactions pricing is therefore variable and the plan is based on purchasing an amount of Tokens per month rather than Transactions. If a user desires closer accounting and measurement of specific Procedures used by their application and a payment plan that reflects this through variable pricing then the use of Tokens may provide added value. The Token cost structure is listed in the following table.

Match Type:

GetPhoneInfo Operation

GetPhoneInfo_V2 Operation

Successful Landline Match:

65 tokens

85 tokens

Successful Wireless Match:

115 tokens

135 tokens

Successful Toll-Free Number Match:

95 tokens

95 tokens

Invalid Phone Number:

5 tokens

5 tokens

Exchange Level Match:

15 tokens

35 tokens


Note: GetPhoneInfo_V2 adds an enhanced data set that can return name contact info for all transactions that have at least a carrier match level (i.e. it is possible to get an exchange level match for 35 tokens that returns a name contact).
The base check is always applied and therefore every transaction will cost at least 5 tokens (for an Invalid Phone Number match). The rest are applied only if a match is found. A carrier match is when basic telephone company information is found. Only one of the contact matches will be used per transaction (whichever best applies). So a landline number with a full contact will be 65 tokens (85 if using V2 operation) and a wireless number with a full contact will be 115 tokens (135 if using V2 operation).

If you decide that use of the Token based structure and pricing plan may be an advantage for you please contact Service Objects Sales Team for assistance: sales@serviceobjects.com or 1-805-963-1700.

Conclusion

ServiceObjects is proud to offer you a free trial of DOTS Address Geocode – CA.

Sign up today for a free trial at:
http://www.serviceobjects.com/products/phone/geophone-plus

Other technical questions or concerns can be directed to support@serviceobjects.com.

If you are interested in purchasing DOTS GeoPhone Plus, please contact sales@serviceobjects.com.

We welcome your feedback! Please do not hesitate to let us know what you think of our web services, documentation, or customer support.
www.serviceobjects.com