Global Phone:Transition

From Melissa Data Wiki
Jump to navigation Jump to search

← Global Phone V4


Overview

Melissa data has recently announced the depreciation of Global Phone V3 service with the transition to our V4 service. The new version has new features and improvements to help improve phone accuracy, along with constant updates every month.

Improvements

This service has several improvements including:

  • Premium Home Location Register (HLR) lookup, which checks a phone in real time for improved accuracy
  • Improved accuracy and coverage of phones worldwide
  • Improved logic of searching depending on user input, additional ways to input phone numbers
  • Additional fields such as suggestions and phone carrier
  • Several updates per month with new features and improvements

With major changes to our data and service, it is no longer feasible for Melissa Data to support the older Global Phone V3 Web Service data. The Global Phone V3 Web Service is being deprecated and the service will no longer be accessible after January 15th, 2017. We are confident you will find that our Global Phone V4 Web Service can do everything the old service did, and more. Please switch over to our new Web service as soon as possible. 


Access and License

All existing Global Phone Web Service subscribers will automatically be given access to our Global Phone V4 web service. When using the V4 service, the same License Key can be used. All royalties according to the subscription agreement will remain the same.


Data Differences

In order to ensure no loss of data, all data fields in Global Phone V3 will also be available in Global Phone V4:

  • Version
  • TransmissionReference
  • Transmission Results
  • Records Array
  • RecordID
  • Results
  • PhoneNumber
  • PhoneInternationalPrefix
  • PhoneCountryDialingCode
  • PhoneNationPrefix
  • PhoneNationalDestinationCode
  • PhoneSubscriberNumber
  • Locality
  • AdministrativeArea
  • CountryName
  • DST
  • UTC
  • Language
  • Latitude
  • Longitude

Additionally, the Global Phone V4 Web Service comes with the following data fields:

Response Field Description
Carrier Provider of the inputted phone number.
CountryAbbreviation The ISO 3166 Alpha-2 code for the country.
InternationalPhoneNumber The full phone number to successfully dial.
PostalCode (US Only) Postal Code for the locality.
Suggestions A list of phone numbers matching, found in different countries


When switching over to Global Phone V4 Web Service, you automatically have access to the new data.


Protocols and URL/Endpoints

Global Phone v4 is now only limited to REST and JSON for requests, and JSON only for responses. You can perform batch querying only in JSON. There is only one service point for both REST and JSON.

Protocol URL
REST, JSON https://globalphone.melissadata.net/v4/WEB/GlobalPhone/doGlobalPhone


Global Phone V4 is available in both http and https:

Protocol URL
Standard http://globalphone.melissadata.net/v4/WEB/GlobalPhone/doGlobalPhone
Secure https://globalphone.melissadata.net/v4/WEB/GlobalPhone/doGlobalPhone


REST Transition

The REST request for Global Phone V4 remains the same, except for service endpoints.  Here is a comparison between the old service and the new service:

Global Phone V3

http://globalphone.melissadata.net/v3/WEB/GlobalPhone/doGlobalPhone?t=&id=xxxxxxxx&phone=4084161451&ctry=US&format=JSON

Global Phone V4

https://globalphone.melissadata.net/v4/WEB/GlobalPhone/doGlobalPhone?t=&id=xxxxxxxx&opt=VERIFYPHONE:Express&phone=4084161451&ctry=US

Note: The response for both REST and JSON will always return as JSON. Please see the section JSON protocol to understand the structure of our V4 JSON response.

The reference guide and sample code in the wiki pages also show how to correctly make a REST request and parse the JSON response. Global Phone V4 Wiki Page.


SOAP and XML Transition

The SOAP and XML Protocols in Global Phone V4 Web Service have been deprecated and are currently not available at this time. This is a design decision made in order to accommodate JSON, which is a relatively newer technology and has grown in popularity.

JSON offers a more flexible Web Service response structure, and supports a dynamic structure in the response. This allows for a more optimal response with less overhead. It also allows for the addition of new output elements without having to re-consume the web service, which is typically an issue when bound by a statically defined structure or WSDL.


JSON Protocol

Previously, the responses were available in JSON and XML format. The new Global Phone V4 Web Service is handled in JSON. The JSON Protocol provides an intuitive and simple way to define the requests and responses.

Below is an example of a JSON request to our Global Phone V4 Web Service:

{
"CustomerID":"103114769",
"TransmissionReference":"",
"Options":"VERIFYPHONE:Express",
"Records":
        [
            {
                "RecordID":"1",
                "PhoneNumber":"${phone1}",
                "Country":"${country1}",
                "CountryOfOrigin":"${countryOrg1}"
            }
       ]
}

Below is an example of a JSON response:

{
"Version": "4.0.0.26",
"TransmissionReference": "SampleJSON",
"TransmissionResults": "",
"Records": [
{
"RecordID": "1",
"Results": "PS01,PS07,PS20",
"PhoneNumber": "4084161451",
"AdministrativeArea": "California",
"CountryAbbreviation": "US",
"CountryName": "United States",
"Carrier": "NEW CINGULAR WIRLESS",
"DST": "Y",
"InternationalPhoneNumber": "+1 4084161450"
"Language": "English",
"Latitude": "37.43492839429599",
"Locality": "San Jose",
"Longitude": "-121.910443520979",
"PhoneInternationalPrefix": "",
"PhoneCountryDialingCode": "1",
"PhoneNationPrefix": "1",
"PhoneNationalDestinationCode": "408",
"PhoneSubscriberNumber": "4161451",
"UTC": "-08:00",
"PostalCode":"95137",
"Suggestions": null
}
]
}


Similar to the request, the response is formatted in the same way with each variable clearly and intuitively labeled in the JSON Response. All previous data fields in the Global Phone V3 Web Service are accessible in V4. The following additional information are also included which were not available in the previous previous version: Carrier, CountryAbbreviation, and Suggestions.

Sample JSON Implementation as well as the reference guide can be found here.


Interpreting Results

The complete list of result codes for Global Phone V4 Web Service can be found here: Global Phone Result Codes.

The result codes for V3 and V4 are identical.

From the above JSON section, our phone number 4084161451 came with the result codes PS01, PS07, and PS20.

PS01 means there was a match found, PS07 means the number is for a mobile phone, and PS20 means the phone was verified with low confidence.