Reference Guide#

Introduction #

Use Phone Object to reduce data entry errors, catch area code splits early, save time looking up area codes, provide dealer lookup for customers, and link U.S. numbers to city, state, ZIP Code and county.

Phone Object takes a phone number with an area code, parses it and validates the number to either the 7-digit or 10-digit level. It can also identify phone numbers as land lines, wireless or Voice Over IP (VOIP) as well as distinguish between business and residential phone numbers. It can also add geographic data corresponding to the area code and prefix and update phone numbers that have undergone a recent area code split, helping to keep your data current and error-free.

Also, by parsing your phone number data and relating each area code and prefix to geographic information, such as longitude and latitude, Phone Object can be used as a tool for planning a marketing campaign.

You can use Phone Object to:

Verify U.S. or Canadian phone numbers down to 7 or 10 digits.
Update the area code if it changed in the last year.
Append data on the telephone line, distinguishing between landlines, wireless numbers, or Voice Over IP (VOIP).
Append data on the telephone owner, distinguishing between residential, business, or home office numbers.
Parse the phone number into its components.
Correct wrong or missing area codes (ZIP Code required).
Check the distance from the phone number to the ZIP Code.

Setup and List of Files #

To see how to set up the Phone Object, the list of files that will be downloaded and used, and the system requirements to run the Object, please visit the GitHub Sample Code.

Methods #

Initialize Phone Object - Set #

These functions initialize Phone Object and connect it to its data files.

Initialize #

Syntax:: Initialize(String_DataPath)
Returns:: Initialization Status
Return Type:: Integer

The Initialize function opens the necessary data files and prepares the Phone Object for use.

If the function returns any value other than 0, call the GetInitializeErrorString function to retrieve the cause of the failure.

Input Parameters

The Initialize function has one parameter:

String_DataPath - A String that contains the path to the location of the mdPhone.dat, mdPhone.idx, mdAddr.dat and NPA.TXT file.

Return Value

The Initialize function returns an integer value of 0 if successful.

SetLicenseString #

Syntax:: SetLicenseString(String_License)
Returns:: Is License Valid
Return Type:: Boolean

The License String is a software key (supplied by the developer) that unlocks the full functionality of Phone Object.

The license string is included with the documentation you received. If you have not purchased a license, call Melissa Data toll free at 1-800-MELISSA (1-800-635-4772) or send an email to sales@MelissaData.com.

The license string is normally set using an environment variable, either MD_LICENSE or MD_LICENSE_DEMO. Calling SetLicenseString is an alternative method for setting the license string, but applications developed for a production environment should only use the environment variable.

When using an environment variable, it is not necessary to call the SetLicenseString function.

If the license string has not been set, Phone Object will operate in a demonstration mode (limited to Nevada Area Codes) and will return the string “DEMO” after the GetBuildNumber function.

Input Parameters

The SetLicenseString function has one parameter:

LicenseString - A string value representing the software license key.

Return Value

The SetLicenseString function returns a Boolean value of 0 (FALSE) or 1 (TRUE). The SetLicenseString function will return a FALSE Boolean value if the license string provided is incorrect.

Initialize Phone Object - Get #

The following functions get values related to the initialization process.

GetBuildNumber #

Syntax:: GetBuildNumber();
Returns:: Build Number
Return Type:: String

The GetBuildNumber function returns the current development release build number of the Phone Object.

The word “DEMO” will be reported after the build number if no license string is provided, or if an incorrect license string is entered.

GetDatabaseDate #

Syntax:: GetDatabaseDate();
Returns:: Database Date
Return Type:: String

The GetDatabaseDate function returns a string value that represents the date of the phone data files.

If the GetDatabaseDate function is called before the Initialize function is called and the data files are not in the same directory as the PHONEOBJ.DLL, this function will return a date outside the normal range of the system date, such as 1969 or 1899, depending on the system.

GetInitializeErrorString #

Syntax:: GetInitializeErrorString();
Returns:: Error Description
Return Type:: String

The GetInitializeErrorString function returns a string describing the error caused when the Initialize function fails.

GetLicenseExpirationDate #

Syntax:: GetLicenseExpirationDate();
Returns:: License Expiration Date
Return Type:: String

License strings issued by Melissa Data are valid for a certain period of time. This function returns the date after which the current license string is no longer valid.

Look Up Phone Numbers #

These two functions look up a phone number, checking either for geographic data or an area code that was updated due to an area code split

CorrectAreaCode #

Syntax:: CorrectAreaCode(PhoneNum, ZIPCode);
Returns:: Is Correction Successful
Return Type:: Boolean

The CorrectAreaCode function will return the correct area code for a phone number and ZIP Code combination to the NewAreaCode. The CorrectAreaCode function will also populate the values returned by GetAreaCode and GetResults functions.

On a FALSE return, the CorrectAreaCode function will set the GetResults function to indicate the cause of failure.

Input Parameters

The CorrectAreaCode function has these parameters:

PhoneNum - A 24 character (maximum) string containing the phone number.
ZIPCode - A five-character VARIANT containing the ZIP Code.

Return Value

The CorrectAreaCode function returns a Boolean value of TRUE if the function call was successful, FALSE if there was an error.

Lookup #

Syntax:: Lookup(Phone[, ZIPCode]);
Returns:: Is Number Valid
Return Type:: Boolean

The Lookup function verifies the submitted phone number down to the first 7 or 10 digits and returns geographic information for the submitted phone number.

On a FALSE return, the state and country code fields might still be populated if the area code is valid. Use the GetResults function to determine if the problem is a prefix error. If this is the case, you can use the GetState and GetCountryCode functions.

The return values of following functions are set by the Lookup function

GetResults             GetAreaCode             GetPrefix
GetSuffix              GetExtension            GetCity
GetState               GetCountyName           GetCountyFips
GetCountryCode         GetDistance             GetLatitude
GetLongitude           GetMsa                  GetPmsa
GetTimeZone            GetTimeZoneCode

Input Parameters

Phone - A 24-character (maximum) string containing the phone number.
- Phone numbers from outside the U.S. and Canada will be not be validated.
- Toll free numbers will be parsed, but not verified.
- Phone Object will recognize a leading country code from U.S. and Canadian phone numbers (i.e. a “1”) and strip that digit before parsing the phone number.
- Any extensions (any consecutive digits after first ten) will be parsed out and returned by the GetExtension function.
ZIPCode - A five-character (optional) ZIP Code. If the ZIP Code is provided, the GetDistance function will contain the distance between the area code/prefix and the ZIP Code.
- If your programming language does not support optional parameters, you should pass an empty string (“”) to the function.
- The ZIPCode parameter only accepts U.S. ZIP codes and not Canadian Postal Codes.
- Because of phone number portability, the number returned by the GetDistance function may not be accurate

Return Value

The Lookup function returns a value of (1) TRUE if the area code/prefix combination is valid and a value of (0) FALSE if it is invalid.

After calling the Lookup function, check the return values of the GetResults function. This will indicate the level of match, the type of phone number verified, and the cause of any errors.

Retrieve Status Information #

These function retrieve information about the most recent calls to the Lookup and CorrectAreaCode functions. The GetErrorCode and GetStatusCode functions have been deprecated in favor of the GetResults function.

GetResults #

Syntax:: GetResults();
Returns:: Result Codes
Return Type:: String

This function returns a comma-delimited string of four-character codes which detail the level of matching found for the current phone number and any errors that occurred during the last call to the Lookup function.

The GetResults function is intended to replace the GetStatusCode and GetErrorCode functions, providing a single source of information about the last Lookup call and eliminating the need to call multiple functions to determine if a particular phone number was verified.

The function returns one or more Results Codes in a comma-delimited list. For a list of these Results Codes, see Results Codes on the bottom of the page.

GetResultCodeDescription #

Syntax:: GetResultCodeDescription(String_ResultCode, ResultCdDescOpt);
Returns:: Result Code Description
Return Type:: String

This function returns the description of the inputted Result Code. It can only be used through the Standard DLL.

It requires two values to be passed in, a Result Code and an enumerated option. If a string of Result Codes are inputted, only the first code will be used. The enumerated option will determine whether a short or long description will be returned.

ResultCdDescOp

Enumerated Value	Integer Value	Description
ResultCodeDescriptionLong	0	Returns a detailed description of the inputted result code.
ResultCodeDescriptionShort	1	Returns a brief description of the inputted result code.

Retrieve Phone Number Data #

These functions retrieve information about the phone number passed via the last call to the Lookup function.

GetAreaCode #

Syntax:: GetAreaCode();
Returns:: Area Code
Return Type:: String

This function returns the area code of the phone number string that was passed to the CorrectAreaCode or Lookup function.

The GetAreaCode function returns a three-character string value set by a call to the CorrectAreaCode or Lookup function.

If there are not enough digits for the area code, this function will be empty. If the area code/prefix combination has been split, the new area code will be in the GetNewAreaCode function. If a ZIP Code was also passed in and corrections were made to the area code, these corrections will appear in the GetNewAreaCode function. If the CorrectAreaCode or Lookup function has not been called, or the call resulted in an error, this function will be blank.

GetExtension #

Syntax:: GetExtension();
Returns:: Extension
Return Type:: String

This function returns the extension (if any) of the phone number passed to the CorrectAreaCode function or the Lookup function.

The GetExtension function returns a maximum 10-character string value set after a call to the CorrectAreaCode function or the Lookup function.

If the CorrectAreaCode function or the Lookup function has not been called, or resulted in an error, this function will be blank.

GetNewAreaCode #

Syntax:: GetNewAreaCode();
Returns:: Modified Area Code
Return Type:: String

This function returns the new area code if the phone number passed to the CorrectAreaCode function has undergone an area code split.

The GetNewAreaCode function returns a three-character string value after a call to the CorrectAreaCode function.

Example: “714”

The GetNewAreaCode function will return a corrected or updated area code based on the phone number string passed into the CorrectAreaCode function.

An area code is corrected when it appears to be invalid for the ZIP Code passed in. Phone Object will change the area code based on the distance between valid area code/prefix combinations and the ZIP Code.

An updated area code is a new area code that is based on the input of an area code/prefix combination that has been split. If no new area code was found, then the GetNewAreaCode function will return the current area code.

If the CorrectAreaCode function has not been called, or resulted in an error, this function will return a null value.

GetPrefix #

Syntax:: GetPrefix();
Returns:: Prefix
Return Type:: String

This function returns the prefix (the first three digits after the area code) of a phone number passed to the CorrectAreaCode function or the Lookup function.

The GetPrefix function returns a three-character string value after a call to the CorrectAreaCode function or the Lookup function.

If the CorrectAreaCode function or Lookup function has not been called, or resulted in an error, this function will be blank.

GetSuffix #

Syntax:: GetSuffix();
Returns:: Suffix
Return Type:: String

This function returns the suffix (last four digits) of the phone number passed to the Lookup function.

The GetSuffix function returns a four-character string value after a call to the Lookup function.

If the Lookup function has not been called, or resulted in an error, the return value of the GetSuffix function will be a blank string.

Retrieve GeoCode Data #

The following functions retrieve geographic data about the phone number submitted to the Lookup function.

GetCity #

Syntax:: GetCity();
Returns:: City
Return Type:: String

This function returns the city name associated with the phone number passed to the Lookup function.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

GetCountryCode #

Syntax:: GetCountryCode();
Returns:: Country Code
Return Type:: String

This function returns the two-character abbreviation that indicates the country of origin for the phone number passed to the Lookup function.

Phone Object includes data for American and Canadian area codes. The two-character abbreviation “US” is returned for area codes in the United States, and the two-character abbreviation “CA” is returned for Canadian area codes.

GetCountyName #

Syntax:: GetCountyName();
Returns:: Country Name
Return Type:: String

This function returns the name of the county associated with the phone number passed to the Lookup function.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

GetCountyFips #

Syntax:: GetCountyFips();
Returns:: Country FIPS
Return Type:: String

This function returns the five-digit county FIPS code associated with the phone number passed to the Lookup function.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

The GetCountyFips function returns a five-digit string value after a successful call to the Lookup function.

The Federal Information Processing Standard (FIPS) is a five-digit code defined by the U.S. Census Bureau. The first two digits are the state code and the last three indicate the county within the state.

For example: “06037” is the County FIPS for Los Angeles, CA (“06” is the state code for California and “037” is the county code for Los Angeles).

GetDistance #

Syntax:: GetCountyFips();
Returns:: Country FIPS
Return Type:: String

This function returns the distance in miles from the area code/prefix wire center to the ZIP Code centroid, if a ZIP Code has been passed to the Lookup function in addition to a phone number. The GetDistance function is a five-character (maximum) string value set by a call to the Lookup function.

The GetDistance function returns the distance between the centroids of the ZIP Code and wire center of the area code/prefix number passed into the Lookup function.

Because of phone number portability, the number returned by the GetDistance function may not be accurate.

If the Lookup function has not been called, resulted in an error, or no ZIP Code was passed in, this function will return “9999”.

GetLatitude #

Syntax:: GetLatitude();
Returns:: Latitude
Return Type:: String

This function returns the latitude of the NPA/NXX wire center for the phone number passed to the Lookup function.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Latitude is the geographic coordinate of the NPA/NXX wire center measured in degrees north or south of the equator. (NPA/NXX = area code/prefix).

The GetLatitude function returns a seven-character (max) string value after a call to the Lookup function. It is accurate to four decimal places. Phone numbers within the United States will always return a positive number.

If the Lookup function has not been called, or resulted in an error, this function will return 0.0.

GetLongitude #

Syntax:: GetLongitude();
Returns:: Longitude
Return Type:: String

This function returns the longitude of the NPA/NXX wire center for the phone number passed to the Lookup function.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Longitude is the geographic coordinate of the NPA/NXX wire center measured in degrees east or west of the Greenwich Meridian (NPA/NXX = area code/prefix).

The GetLongitude function returns a nine-character (max) string value after a call to the Lookup function. It is accurate to four decimal places and the negative sign is used to indicate a longitude in the United States.

If the Lookup function has not been called, or resulted in an error, this function will return 0.0.

GetMSA #

Syntax:: GetMSA();
Returns:: Metropolitan Statistical Area
Return Type:: String

This function returns the Metropolitan Statistical Area (MSA) number associated with the phone number passed to the Lookup function.

The Office of Management and Budget defines the Metropolitan Statistical Area (MSA). An MSA consists of one or more counties forming a large population with adjacent communities and having a high degree of social and economic integration.

The GetMsa function returns a four-digit value after a call to the Lookup function. If the Lookup function has not been called, or resulted in an error, this function’s return value will be blank.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

GetPMSA #

Syntax:: GetPMSA();
Returns:: Primary Metropolitan Statistical Area
Return Type:: String

This function returns the Primary Metropolitan Statistical Area (PMSA) number associated with the phone number passed to the Lookup function.

The Office of Management and Budget defines the Primary Metropolitan Statistical Area (PMSA) for regions that contain a population of more than one million.

The GetPmsa function returns a four-digit string value after a call to the Lookup function.

Example: “5495” or “0”

If the Lookup function has not been called, or resulted in an error, this function value will be blank.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

GetState #

Syntax:: GetState();
Returns:: State
Return Type:: String

This function returns the state abbreviation associated with the area code passed to the Lookup function.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

GetTimeZone #

Syntax:: GetTimeZone();
Returns:: Time Zone
Return Type:: String

This function returns a string describing the time zone of the phone number passed to the Lookup function.

All Melissa Data products express time zones in UTC (Coordinated Universal Time).

The GetTimeZone function returns a string value describing the time zone where the phone number is located. The function will return one of the following strings:

::: “Atlantic Time” “Hawaii Time” “Eastern Time” “Samoa Time” “Central Time” “Marshall Islands Time” “Mountain Time” “Guam Time” “Pacific Time” “Palau Time” “Alaska Time”

If the input phone number cannot be corrected by the Lookup function, this string will be blank.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

GetTimeZoneCode #

Syntax:: GetTimeZoneCode();
Returns:: Time Zone Code
Return Type:: String

This function returns a 1 or 2-digit code representing the time zone associated with the phone number passed to the Lookup function.

Following are the possible values for the TimeZoneCode function:

Code	Zone
4	Atlantic Time
5	Eastern Time
6	Central Time
7	Mountain Time
8	Pacific Time
9	Alaska Time
10	Hawaii Time
11	Samoa Time
13	Marshall Island Time
14	Guam Time
15	Palau Time

If the input phone number cannot be corrected by the Lookup function, this string will be blank.

Because of phone number portability, geographical information may not reflect the true location of the owner of the phone number for wireless and VOIP numbers.

Computation Functions #

The following functions do not require the data files to be initialized, but they can be used with the GetLatitude and GetLongitude functions to calculate distances and bearing between two records.

ComputeBearing #

Syntax:: ComputeBearing();
Returns:: Bearing
Return Type:: DoubleFloat

The ComputeBearing function returns a Bearing in degrees (-0 to 360) representing the compass direction from point 1 to point 2.

You do not have to call the Initialize function before calling the ComputeBearing function.

Input Parameters

This function accepts four double-precision floating point numbers.

lat1 - latitude for point 1 [In Degrees (90 to -90)]
long1 - longitude for point 1 [In Degrees (180 to -180)]
lat2 - latitude for point 2 [In Degrees (90 to -90)]
long2 - longitude for point 2 [In Degrees (180 to -180)]

Return Value

The ComputeBearing function returns a double-precision floating point bearing based on input latitudes and longitudes.

ComputeDistance #

Syntax:: ComputeDistance();
Returns:: Distance
Return Type:: DoubleFloat

The ComputeDistance function returns a straight-line distance in miles between point 1 and point 2.

You do not have to call the Initialize function before calling the ComputeDistance function.

Input Parameters

The function accepts four double-precision floating point numbers.

latitude 1 - latitude for point 1 [In Degrees (90 to -90)]
longitude 1 - longitude for point 1 [In Degrees (180 to -180)]
latitude 2 - latitude for point 2 [In Degrees (90 to -90)]
longitude 2 - longitude for point 2 [In Degrees (180 to -180)]

Return Value

The ComputeDistance function returns a double-precision floating point value representing the distance between two points based on the input latitudes and longitudes.

Result Codes #

For details of all result codes please visit here

PS - Phone Status #

Code	Short Description	Long Description
`PS01`	Valid Phone	The phone number has been verified as valid.
`PS02`	7-Digit Match	The first 7-digits of the phone number have been verified, but activity cannot be confirmed.
`PS03`	Corrected Area Code	NewAreaCode contains corrected area code that was changed according to the postal code it falls into.
`PS04`	Demo Mode	Demo mode is active and the phone number is outside the range of phone numbers allowed by the Demo.
`PS05`	Database Expired	The phone database is expired. Please update your data.
`PS06`	Updated Area Code	The area code was changed due to an area code split. The updated code is located within NewAreaCode.
`PS07`	Cellular Line	On activation, the exchange type of the phone number was designated as a cellular number, but current status cannot be confirmed.
`PS08`	Land Line	On activation, the exchange type of the phone number was designated as a land line, but current status cannot be confirmed.
`PS09`	VOIP Line	On activation, the exchange type of the phone number was designated as a VOIP line, but current status cannot be confirmed.
`PS10`	Residential Number	The phone number belongs to a residence.
`PS11`	Business Number	The phone number belongs to a business.
`PS12`	SOHO Number	The phone number belongs to a small office or home office.
`PS13`	Toll Free Number	Global Phone Object Only. The phone number is a toll free number.
`PS14`	Special Number	Global Phone Object Only. This is a phone number with premium service, data, internet access, etc. which all incur a higher charge rate.

PE - Phone Error #

Code	Short Description	Long Description
`PE01`	Invalid Phone	The area code/phone number does not exist in our database or contains non-numbers.
`PE02`	Blank Phone	The phone number is blank.
`PE03`	Bad Phone	The phone number has too many or too few digits.
`PE04`	Multiple Match	Two or more possible area codes are available as a fix and their distance is too close to choose one over the other.
`PE05`	Bad Prefix/Prefix +1	The phone prefix or first 7-digits do not exist in our database.
`PE06`	Bad Postal Code	The input postal code is invalid.
`PE08`	No Country Input	Global Phone Object Only. The input country is blank and the phone number has no ‘+’ sign.
`PE09`	Out of Range Suffix	Global Phone Object Only. The subscriber’s phone number suffix is out of range.
`PE10`	Invalid Input Country	Global Phone Object Only. The input country in not valid.

PC - Phone Change #

Code	Short Description	Long Description
`PC01`	Country Changed	Global Phone Only. The country was added or changed to correspond to the phone number.

Reference Guide

Contents

Reference Guide#