Reference Guide#

Introduction #

Melissa’s GeoCoder Object is a compliment to the Address Object. For users of Address Object, after you have verified and corrected your addresses, use this GeoCoder Object to append geocoding coordinates, census information, school information, and more. GeoCoder covers both the United States and Canada, perfectly mirroring the coverage of Address Object. For Global Geocoding coverage outside of the US and Canada, take a look at our Global Address Object.

Geodetic System

The GeoCoder Object uses WGS 84 standard, an Earth-centered, Earth-fixed terrestrial reference system and geodetic datum.

Census Data Year

Census data changes and updates are made on a regular basis. It is important to know the year of the Census data Melissa is returning so that it can be accurately matched up to your own data or other census values.

Setup and List of Files #

To see how to set up the GeoCoder 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 GeoCoder Object - Set #

These methods initialize GeoCoder Object and connect it to its data files.

InitializeDataFiles #

Syntax:: InitializeDataFiles();
Returns:: Initialization Status
Return Type:: Integer

The InitializeDataFiles function opens the required data files and prepares the GeoCoder Object for use.

Remarks

The SetPathToGeoCodeDataFiles function must be called prior to calling this function.

If this function returns any value other than No Error, call the GetInitializeErrorString function to determine the cause of the failure.

The GeoCoder Object data expires nine months after the date indicated by the GetDatabaseDate function. After this date, a “DataFile Expired” error is returned.

Return Value

The InitializeDataFiles function returns an integer value of 0 if successful, and a non-zero value if unsuccessful.

Return		Return
Value	Initialize Error String	Value	Initialize Error String
0	No error.	2	Insufficient memory to initialize.
-1	Not initialized.	3	County file error.
1	Invalid path to data.	4	Data File Expired.

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 GeoCoder Object.

Remarks

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

If the SetLicenseString function is not called or an incorrect license string is used, GeoCoder Object will not operate.

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.

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). It will return a FALSE Boolean value if the license string provided is incorrect.

SetPathToGeoCanadaDataFiles #

Syntax:: SetPathToGeoCanadaDataFiles();
Return Type:: Void

This function passes a string value containing the path to the data files used by the ComputeDistance function to geocode Canadian postal codes.

Remarks: This function must be called prior to calling the InitializeDataFiles function. It is optional if you do not intend to geocode Canadian addresses. The value must contain a valid path to the directory that contains the Canadian geocoing data file: mdGeoCanada.db.

SetPathToGeoCodeDataFiles #

Syntax:: SetPathToGeoCodeDataFiles();
Return Type:: Void

This function passes a string value containing the path to the data files used by GeoCoder Object.

Remarks: This function must be called prior to calling the InitializeDataFiles function. The value must contain a valid path to the directory that contains the GeoCode data files, mdGeoCode.db3.

WriteToLogFile #

Syntax:: WriteToLogFile(String LogFile);
Returns:: Success
Return Type:: Boolean

This function writes data to a log file.

Remarks: This function must be called prior to calling the InitializeDataFiles function. The value may contain a valid path to the directory you want to contain the log file. Otherwise the log file will be created in the current directory of the program. If the log file cannot be created or written to, this function will return false.
Log File Schema: CustomerID|YYYY-MM-DD hh:mm:ss|GS01 Count|GS02 Count|GS05 Count|GS06 Count|CheckSum

Initialize GeoCoder 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 GeoCoder Object.

Remarks: The word “DEMO” will be returned 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 GetBuildNumber function returns the current development release build number of GeoCoder Object.

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

GetExpirationDate #

Syntax:: GetExpirationDate();
Returns:: Expiration Date
Return Type:: String

The GetExpirationDate function returns a date value representing the date your data files expire. This date allows you to confirm that the data files you are using are the latest ones.

Remarks: If the GetExpirationDate function is called before the InitializeDataFiles function is called, an exception will be reported.
Return Value: The GetExpirationDate function returns a value representing the expiration date of the data files. The COM object returns a date value, while the standard object returns a string value.

GetInitializeErrorString #

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

This function returns a descriptive string to describe any error in a call to the InitializeDataFiles function.

Remarks: If called before the InitializeDataFiles function, this function will return an empty string.

GetLicenseExpirationDate #

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

Returns a string value containing the expiration date of the current license string.

Remarks: Call this function to determine when your current license will expire. After this date, GeoCoder Object will no longer function.

Geocoding ZIP Codes and Addresses #

These methods retrieve the geographic data for multiple attributes (FindGeo method).

ComputeBearing #

Syntax:: ComputeBearing(DoubleFloat lat1, DoubleFloat long1, DoubleFloat lat2, DoubleFloat long2);
Returns:: Bearing
Return Type:: Double Float

The ComputeBearing Method returns a bearing of 0 to 360 degrees representing the compass direction from point 1 to point 2. To convert your bearing to an approximate compass direction, use the following table:

Direction	Degrees	Direction	Degrees
N	0 to 22.5, 337.5 to 0	S	157.5 to 202.5
NE	22.5 to 67.5	SW	202.5 to 247.5
E	67.5 to 112.5	W	247.5 to 292.5
SE	112.5 to 157.5	NW	292.5 to 337.5

Remarks

If an invalid latitude or longitude is entered, a value of 999 will be returned. You do not have to call the GetBuildNumber function before calling the FindGeo function.

Input Parameters

The method 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 Method returns a double-precision bearing based on input latitudes & longitudes.

ComputeDistance #

Syntax:: ComputeDistance(DoubleFloat lat1, DoubleFloat long1, DoubleFloat lat2, DoubleFloat long2);
Returns:: Distance
Return Type:: Double Float

The ComputeDistance Method returns a distance in miles between point 1 and point 2.

Remarks

If an invalid latitude or longitude is entered, a value of 999 will be returned.

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

Input Parameters

The method 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 ComputeDistance Method returns the distance in miles between two points based on the input latitudes & longitudes.

FindGeo #

Syntax:: FindGeo();
Returns:: Success
Return Type:: String

This method performs a lookup on the attributes set by the SetInputParameter method. As such, it is required after the SetInputParameter method.

SetInputParameter is called to give FindGeo data to perform lookups for the GetOutputParameter method. These three methods work together and must be called in the same order at all times: SetInputParameter first, FindGeo second, and finally GetOutputParameter.

SetInputParameter #

Syntax:: SetInputParameter(String KeyString, String ValueString);
Returns:: Success
Return Type:: Boolean

This method sets the input data (in key-value pairs) for the FindGeo lookup method. As such, it is required before the FindGeo method.

SetInputParameter is called to give FindGeo data to perform lookups for the GetOutputParameter method. These three methods work together and must be called in the same order at all times: SetInputParameter first, FindGeo second, and finally GetOutputParameter.

Remarks

All attributes can be set at the same time. The object will do lookups in a top-down order, following the order of the key strings from most significant to least (First MAK, then AddressKey, followed by Zip, etc.) See the list below for the full ordering.

Input Parameters

The SetInputParameter function has the following parameters.

KeyString:: A string value representing thekey.
ValueString:: A string value representing the value.

The available key strings are below, ordered from most significant to least:

Significance	Key Strings	Key String Descriptions
1	MAK	A propietary unique key identifier for an address. This is derived from Address Checking.
2	AddressKey	An 11 digit key of the property. Based on the Zip5, Plus4 and two digit delivery code.
3	Zip	The 5-digit postal code.
4	Plus4	The 4-digit plus4 of the postal code.
5	Latitude	The latitude in degrees. This is the same function as SetLatitude.
6	Longitude	The longitude in degrees. This is the same function as SetLongitude.

Retrieve Results #

The following methods return information on the success of the last call to the ComputeDistance or FindGeo methods.

GetResults #

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

This function returns a string value containing status and error codes for the current record. Multiple codes are separated by commas.

Remarks

The GetResults function may return one or more four-character strings, separated by commas, depending on the result generated by the current record.

Result Codes

If the location information in the current record was valid, this field will contain the value “GS01” at the very minimum and may include more of the “GS” codes. If the address could not be verified, the codes beginning with “GE” will indicate the reason or reasons why verification failed.

GetResultCodeDescription #

Syntax:: GetResultCodeDescription(StringValue_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.

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 Geocode Data #

The following method returns the specified geo information from the last call to the FindGeo method.

GetOutputParameter #

Syntax:: GetOutputParameter(StringValue_ResultCode,ResultCdDescOpt);
Returns:: Result Code Description
Return Type:: String

This method returns the GeoCoded element requested and looked-up by the FindGeo method. As such, it is required after the SetInputParameter and FindGeo methods, in that order.

SetInputParameter is called to give FindGeo data to perform lookups for the GetOutputParameter method. These three methods work together and must be called in the same order at all times: SetInputParameter first, FindGeo second, and finally GetOutputParameter.

Remarks

The FindGeo method must be called prior to calling this method.

The possible element names you can request are as follows:

Element Name	Description
BlockSuffix	If the CensusKey is 15-characters, this will be empty. If the CensusKey is 16-characters, the last character is the BlockSuffix.
CBSACode	5-digit code for the CBSA.
CBSATitle	Title for the CBSA, if any.
CBSALevel	Level (metropolitan or micropolitan) of the CBSA, if any.
CBSADivisionCode	Code for the CBSA division, if any.
CBSADivisionTitle	Title for the CBSA division, if any.
CBSADivisionLevel	Division Level (metropolitan or micropolitan) of the CBSA division, if any.
CensusBlock	Census Block as defined by the U.S. Census Bureau.
CensusKey	15-digit string containing the concatenated County FIPS, Census Tract and Census Block.
CensusKeyDecennial	15-digit string containing the concatenated County FIPS, Census Tract, and Census Block for the most recent Decennial Census. The Decennial Census occurs every 10 years with the most recent available being 2010.
CensusTract	Census Tract as defined by the U.S. Census Bureau.
CountyFips	5-digit numeric Federal Information Processing Standard (FIPS) code.
CountyName	The name of the county.
CountySubdivisionCode	5-digit string representing the County Subdivision Code.
CountySubdivisionName	The County Subdivision Name.
ElementarySchoolDistrictCode	5-digit string representing the Elementary School District Code.
ElementarySchoolDistrictName	The Elementary School District Name.
Latitude	The latitude in degrees.
Longitude	The longitude in degrees.
LSAD	2-digit string representing the Legal/Statistical Area Description. For a list of all LSAD codes, see https://www.census.gov/library/reference/codelists/legal-status-codes.html.
PlaceCode	The area code located outside of a city but within the ZIP Code.
PlaceName	The area name located outside of a city but within the ZIP Code.
Results	Comma delimited status, error codes, and change codes.
SecondarySchoolDistrictCode	5-digit string representing the Secondary School District Code.
SecondarySchoolDistrictName	The Secondary School District Name.
StateDistrictLower	3-digit string representing the Lower State District Code.
StateDistrictUpper	3-digit string representing the Upper State District Code.
TimeZone	The Time Zone name.
TimeZoneCode	3-letter string representing the Time Zone Code.
UnifiedSchoolDistrictCode	5-digit string representing the Unified School District Code.
UnifiedSchoolDistrictName	The Secondary Unified District Name.

If the FindGeo method was not called first, the return value of this method will be an empty string.

Deprecated Methods #

The following methods have been deprecated. While you can use this reference to continue using these deprecated methods, we strongly recommend you use the newer methods: SetInputParameter, FindGeo, and GetOutputParameter.

GeoCode #

Syntax:: GeoCode(String Zip, String Plus4);
Returns:: Status
Return Type:: Boolean

This function obtains and sets the return values of the GeoCoder Object with Geographic and Census data, using an input ZIP Code and Plus4.

Remarks

If a 9-digit ZIP Code or 5-digit ZIP Code and Plus4 are used as parameters for the GeoCode function, the following will be done in order, if the previous fails:

Information will be obtained from the full ZIP and Plus4 combination. The GetResults function will return “GS01.”
If no information is found for the Plus4, the centroid for the ZIP+2 segment will be used (The ZIP Code & first two digits of the Plus4). The GetResults function will return “GS02.”
If the ZIP+2 segment cannot be found, the centroid for the 5-digit ZIP Code will be used. The GetResults function will return “GS03.”

Input Parameters

The GeoCode function has the following parameters:

Zip (Required):: The 5-digit ZIP Code, 9-digit ZIP + 4 code, or 6-digit Canadian Postal Code. A ZIP Code can consist of five digits to represent a 5-digit ZIP Code, or nine digits to represent a ZIP + 4 code. If the ZIP + 4ZIP + 4 is included here, a hyphen can be used to separate the two numbers, but is not required.
Plus4 (Optional):: The 4-digit Plus4 code if not included with the ZIP parameter.

When geocoding Canadian postal codes the full six-digit postal code must be included in the first parameter (Zip),

Return Value

The GeoCode function returns a Boolean value of 0 (FALSE) or 1 (TRUE).

A TRUE return will set the return values of the various functions described in the section beginning on page 23. On a FALSE return, check the GetResults function.

GeoPoint #

Syntax:: GeoPoint(String AddressKey, "", ""); GeoPoint(String ZipCode, String Plus4, String DPC);
Returns:: Status
Return Type:: Boolean

Obtains and sets the return values of the GeoCoder Object with Geographic and Census data, using an input ZIP Code, Plus4 and delivery point code. If successful, the data will be accurate to the rooftop level, rather than just the ZIP + 4 code, as with the ComputeDistance function.

Remarks

If a five-digit ZIP Code, Plus4 and valid delivery point are used as parameters for the GeoPoint function, the following will be done in order, if the previous fails:

Rooftop-level information will be obtained for the full combination of ZIP Code, Plus4 and Delivery Point Code (Result Code “GS05”).
If the Delivery Point Code is not found, information will be returned for the centroid of the ZIP and Plus4 combination (Result Code “GS01”).
If no information is found for the Plus4, the centroid for the ZIP+2 (The ZIP Code & first two digits of the Plus4) segment will be used (Result Code “GS02”).
If the ZIP+2 segment cannot be found, the centroid for the 5-digit ZIP Code will be used (Result Code “GS03”)
Check the return value of the GetResults function to verify the level to which the record was coded.

Input Parameters

The GeoPoint function can use one of the two following sets of string values as parameters:

AddressKey:: This is the preferred input. The 11-digit AddressKey contains all the information that the object requires. If the AddressKey input is used, do not use the other input parameters.

Or:

Zip:: The 5-digit ZIP Code, 9-digit ZIP + 4 code, or 6-digit Canadian Postal Code. A ZIP Code can consist of five digits to represent a 5-digit ZIP Code, or nine digits to represent a ZIP + 4 code. If the ZIP + 4 is included here, a hyphen can be used to separate the two numbers, but is not required.
Plus4:: The four-digit Plus4 code.
DeliveryPoint:: Code The two-digit Delivery Point Code.

The AddressKey parameter is the preferred input. However either the AddressKey or the combination of Zip, Plus4, and DeliveryPoint Code are valid. For Canadian records, the Plus4 and DeliveryPoint Code parameters must be blank.

Refer to the syntax below for an example usage of both inputs.

Return Value

The GeoPoint function returns a Boolean value of 0 (FALSE) or 1 (TRUE).

A TRUE return will set the return values of the functions described in the section beginning on page 23. On a FALSE return, check the GetResults function.

GetCBSACode #

Syntax:: GetCBSACode();
Returns:: CBSA Code
Return Type:: String

This function returns the five-digit code for the Core Based Statistical Area (CBSA).

Remarks

Metropolitan and micropolitan statistical areas (metro and micro areas) are geographic entities defined by the U.S. Office of Management and Budget (OMB) for use by Federal statistical agencies in collecting, tabulating, and publishing Federal statistics. The term “Core Based Statistical Area” (CBSA) is a collective term for both metro and micro areas. A metro area contains a core urban area of 50,000 or more population, and a micro area contains an urban core of at least 10,000 (but less than 50,000) population. Each metro or micro area consists of one or more counties and includes the counties containing the core urban area, as well as any adjacent counties that have a high degree of social and economic integration (as measured by commuting to work) with the urban core.

The CBSA Code is a five-digit code for the specific CBSA associated with the location described by the submitted ZIP Code.

GetCBSADivisionCode #

Syntax:: GetCBSADivisionCode();
Returns:: CBSA Division Code
Return Type:: String

This function returns the numeric code for the division within the Core Based Statistical Area containing the submitted ZIP Code.

Remarks: Some CBSA’s are broken into parts known as divisions. In this case, the CBSA Division functions will also be populated. If not, these fields will be empty. Each division also has a Code, Level and Title.

GetCBSADivisionLevel #

Syntax:: GetCBSADivisionLevel();
Returns:: CBSA Division Level
Return Type:: String

This function returns the numeric code for the division within the Core Based Statistical Area containing the submitted ZIP Code.

Remarks: Some CBSA’s are broken into parts known as divisions. In this case, the CBSA Division functions will also be populated. If not, these fields will be empty. Each division also has a Code, Level and Title.

GetCBSADivisionTitle #

Syntax:: GetCBSADivisionTitle();
Returns:: CBSA Division Title
Return Type:: String

This function returns the official U.S. Census Bureau’s official name for the division within the Core Based Statistical Area containing the submitted ZIP Code.

Remarks: Some CBSA’s are broken into parts known as divisions. In this case, the CBSA Division functions will also be populated. If not, these fields will be empty. Each division also has a Code, Level and Title.

GetCBSALevel #

Syntax:: GetCBSALevel();
Returns:: CBSA Level
Return Type:: String

This function returns the level description for the Core Based Statistical Area (CBSA), metropolitan or micropolitan.

Remarks: For more information on Core Based Statistical Areas, see the GetOutputParameter function on page 23.

GetCBSATitle #

Syntax:: GetCBSATitle();
Returns:: CBSA Title
Return Type:: String

Returns the official U.S. Census Bureau name for the Core Based Statistical Area (CBSA).

Remarks: For more information on Core Based Statistical Areas, see the GetOutputParameter function on page 23.

GetCensusBlock #

Syntax:: GetCensusBlock();
Returns:: Census Block
Return Type:: String

This function returns the Census Block number for the submitted ZIP + 4, returned after a successful call to the ComputeDistance or GeoPoint function.

Remarks

Census blocks, the smallest geographic area for which the Bureau of the Census collects and tabulates decennial census data, are formed by streets, roads, railroads, streams and other bodies of water, other visible physical and cultural features, and the legal boundaries shown on Census Bureau maps.

A Census Block Group is a cluster of blocks having the same first digit of their 3-digit identifying numbers within a Census Tract or Block Numbering Area (BNA). For example, Census Block Group 3 within a Census Tractor BNA includes all blocks numbered between 301 and 397. In most cases, the numbering involves substantially fewer than 97 blocks. Census Block Groups never cross Census Tract or BNA boundaries, however, they may cross the boundaries of county subdivisions, places, American Indian and Alaskan Native areas, urbanized areas, voting districts, and congressional districts. Census Block Groups generally contain between 250 and 550 housing units, with the ideal size being 400 housing units.

Census Blocks are small areas bordered on all sides by visible features such as streets, roads, streams, and railroad tracks, and by invisible boundaries such as city, town, township, county limits, property lines, and short, imaginary extensions of streets and roads.

The GetCensusBlock function returns a 4-character string value after a call to the ComputeDistance or GeoPoint function. The first digit is the Block Group and the last three characters (if any) are the Block Number.

Example:

“103A” (Block Group is 1 & Block Number is 3A)

If neither the ComputeDistance nor the GeoPoint function have been called, or if the function call resulted in an error, this function value will be empty.

GetCensusTract #

Syntax:: GetCensusTract();
Returns:: Census Tract
Return Type:: String

This function returns the Census Tract number for the submitted location, returned after a successful call to the ComputeDistance or GeoPoint function.

Remarks

Census Tracts are small, relatively permanent statistical subdivisions of a county. Census Tracts are delineated for all metropolitan areas (MA’s) and other densely populated counties by local census statistical areas committees following Census Bureau guidelines (more than 3,000 Census Tracts have been established in 221 counties outside MA’s).

The GetCensusTract function returns a four or six-character string value after a successful call to either the ComputeDistance or the GeoPoint function.

The Census Tract is usually returned as a 4-digit number. However, in areas that experience substantial growth, a Census Tract may be split to keep the population level even. When this happens, a 6-digit number will be returned.

If neither the ComputeDistance nor the GeoPoint function has been called, or if the function call resulted in an error, this value will be an empty string.

GetCountyFips #

Syntax:: GetCountyFips();
Returns:: County FIPS Code
Return Type:: String

This function returns the County FIPS code for the submitted ZIP Code, after a successful call to either the ComputeDistance or the GeoPoint function.

Remarks

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

The GetCountyFips function returns a 5-character string value set by a call to the ComputeDistance or GeoPoint function. It is accurate to the 9-digit level.

Example:

“06037” is the County FIPS for Los Angeles, CA.

In the example above, “06” is the state code for California and “037” is the county code for Los Angeles.

If neither the ComputeDistance nor the GeoPoint function has been called, or if the function call resulted in an error, this value will be an empty string.

GetCountyName #

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

This function returns the County name for the submitted ZIP Code after a successful call to either the ComputeDistance or the GeoPoint function.

Remarks

The GetCountyName function returns a 25-character (maximum) string after a successful call to either the ComputeDistance or the GeoPoint function.

If neither the ComputeDistance nor the GeoPoint function has been called, or if the function call resulted in an error, this value will be an empty string.

GetErrorCode #

Syntax:: GetErrorCode();
Returns:: Error Code
Return Type:: String

This function returns error code triggered by an unsuccessful call to the ComputeDistance or GeoPoint function.

Since this has been deprecated you should use the GetResults function instead. See page 21 for documentation on this function.

Remarks

This function returns s a 1-character string value after an unsuccessful call to the ComputeDistance or GeoPoint function.

Possible return values from the GetErrorCode function are as follows:

Error
Code	Reason for Error
N	Record Not Found — Unable to locate the ZIP Code.
Z	Bad ZIP Code (an invalid ZIP Code was entered, for example, “abcde”)

If neither the ComputeDistance nor the GeoPoint function have been called, or if the function call did not result in an error, the return value of this function will be an empty string.

GetLatitude #

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

This function returns the latitude for the submitted location after a successful call to either the ComputeDistance or the GeoPoint function.

Remarks

Latitude is the geographic coordinate of a point measured in degrees north or south of the equator. The GeoCoder Object uses the WGS-84 standard for determining latitude.

The GetLatitude function returns a character string representing a numeric value, set by a call to either the ComputeDistance or the GeoPoint function.

Since all U.S. ZIP Code latitude coordinates are north of the equator, this value will always be positive.

If neither the ComputeDistance nor the GeoPoint function has been called, or if the function call 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 submitted location after a successful call to either the ComputeDistance or the GeoPoint function.

Remarks

Longitude is the geographic coordinate of a point measured in degrees east or west of the Greenwich meridian. The GeoCoder Object uses the WGS-84 standard for determining longitude.

The GetLongitude function returns an 11-character string value set by a call to either the ComputeDistance or the GeoPoint function. Its negative number indicates a point west of the Greenwich meridian.

If neither the ComputeDistance nor the GeoPoint function has been called, or if the function call resulted in an error, this function will return “0.0.”

GetPlaceCode #

Syntax:: GetPlaceCode();
Returns:: Place Code
Return Type:: String

This function returns the Census Bureau place code associated with the location passed to either the ComputeDistance or the GeoPoint function.

Remarks

The GetPlaceCode function returns a seven-digit string value containing the Census place code for the submitted location.

ZIP Code boundaries sometime overlap with city limits and unincorporated areas. The ZIP Code may place a location within one city even though it is physically located within a neighboring area. The place code matches the ZIP + 4 code with the Census bureau’s official name for that physical location.

If neither the ComputeDistance nor the GeoPoint function has been called, the submitted data was only a five-digit ZIP Code or if the function call resulted in an error, this function value will return an empty string value.

GetPlaceName #

Syntax:: GetPlaceName();
Returns:: Place Name
Return Type:: String

This function returns the Census Bureau place name associated with location passed to either the ComputeDistance or the GeoPoint function.

Remarks

The GetPlaceName function returns a 60-digit string value containing the Census place name for the submitted location.

ZIP Code boundaries sometime overlap with city limits and unincorporated areas. The ZIP Code may place a location within one city even though it is physically located within a neighboring area. This function returns the Census bureau’s official name for the ZIP + 4 code.

For example, the 92688 ZIP Code is located mostly within the city of Rancho Santa Margarita. However, it also contains parts of the unincorporated area of Los Flores. For these ZIP + 4 codes, the GetCity function of Address Object would return “Rancho Santa Margarita,” but this function will return “Los Flores.”

GetStatusCode #

Syntax:: GetStatusCode();
Returns:: Status Code
Return Type:: String

The Status Code indicates how precisely the ComputeDistance or GeoPoint information was matched after a successful call to either of those functions.

Since this has been deprecated you should use the GetResults function instead. See page 21 for documentation on this function.

Remarks

The GetStatusCode function returns a one-character string value after a call to the ComputeDistance or GeoPoint function.

Possible return values from the GetStatusCode function are as follows:

Status
Code	Explanation
B	Record was coded to rooftop level.
A	Record was coded to interpolated rooftop level.
9	Record was coded to the ZIP + 4 centroid (U.S.) or or the full 6-digit Postal Code level (Canada).
7	Record was coded to the ZIP + 2 centroid.
5	Record was coded to the 5-digit ZIP Code centroid (U.S.) or or the first 3- digit Postal Code level (Canada).
X	Record was not coded.
D	This object is in “Demonstration” mode and it detected the input of a ZIP Code outside the allowable range.
E	Expired.

If neither the ComputeDistance function nor the GeoPoint function have not been called, this function will return an empty string.

GetTimeZone #

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

This function returns the name of the time zone for the submitted location.

Remarks

All Melissa Data products express time zones in UTC (Coordinated Universal Time). This function will return one of the values under the Name column in the following table.

Code	Name	Code	Name
0	Military (APO or FPO)	9	Alaska Time
4	Atlantic Time	10	Hawaii Time
5	Eastern Time	11	Samoa Time
6	Central Time	13	Marshall Islands Time
7	Mountain Time	14	Guam Time
8	Pacific Time 15		Palau Time

The values under the Code column are returned by the GetTimeZoneCode function.

GetTimeZoneCode #

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

This function returns a numeric code for the time zone for the submitted location.

Remarks: For a list of the possible values returned by this function, see the table on page 49.

Initialize #

Syntax:: Initialize(String DataPath, String IndexPath);
Returns:: Status
Return Type:: Integer

Since this has been deprecated you should use the InitializeDataFiles function. It may still be called instead of the InitializeDataFiles function if the GeoPoint functionality is not being used, but calling the InitializeDataFiles function is now the preferred method and required for using the GeoPoint function.

This function opens the required data files and prepares the GeoCoder Object for use.

Remarks

If this function returns any value other than 0, call the GetBuildNumber function to determine the cause of the failure.

GeoCoder data expires nine months after the GeoCoder Object database date. After this date, a “DataFile Expired” error is returned.

Input Parameters

The Initialize function has the following optional parameters:

DataPath:

A string containing the path to the mdGeoCode.db3 and mdGeo.lic file locations.

The path parameter is optional. If the path is not given, the Initialize function will look for this data file in the same directory as the GeoObj.dll file (for Windows) or the target directory (for Unix).

IndexPath:

A string containing the path to the mdGeo.idx and mdGeo.cty file locations.

Return Value

The Initialize function returns the same values as the InitializeDataFiles function, show in the table on page 12.

SetLatitude #

Syntax:: SetLatitude(String Latitude);
Return Type:: Void

Use of the SetLatitude or SetLongitude functions will prevent records previously coded with GeoCoder Object from being counted towards your overall usage. By setting these properties to the values previously returned from GeoCoder Object, any records whose current values match the values set in the properties will not be counted against your total usage.

SetLongitude #

Syntax:: SetLongitude(String Latitude);
Return Type:: Void

SetPathToGeoPointDataFiles #

Syntax:: SetPathToGeoPointDataFiles(String Latitude);
Return Type:: Void

This function passes a string value containing the path to the data files used by the GeoPoint function of GeoCoder Object.

Remarks

This function must be called prior to calling the InitializeDataFiles function. It is optional if you do not intend to use the GeoPoint function.

The value must contain a valid path to the directory that contains the GeoPoint data files, mdGeoCode.db3.

Result Codes #

For details of all result codes please visit here

GS - Geocode Status #

Code	Short Description	Long Description
`GS01`	Geocoded to Street Level	The record was coded to the street level (Zip+4 for US, full postal code for CA).
`GS02`	Geocoded to the Neighborhood Level	The record was geocoded down to neighborhood level (Zip+2 for US).
`GS03`	Geocoded to Community Level	The record was coded to the community level (ZIP centroid for US, 3-digit postal code for CA).
`GS05`	Geocoded to Rooftop Level	The record was geocoded down to the rooftop level, meaning the point is within the property boundaries, usually the center.
`GS06`	Geocoded to Interpolated Rooftop Level	The record was geocoded down to the rooftop level using interpolation (educated estimations using street coordinates). The point may be in or close to the property boundaries.

GE - Geocode Error #

Code	Short Description	Long Description
`GE01`	Regional Geocode Not Found	Geocode could not be appended for the input locality or postal code.
`GE02`	No Geocode for Input Address	The input address did not provide enough valid information to append a geocode.
`GE03`	Demo Mode	Geocoder is in Demo mode and a zip code outside the Demo range was detected.
`GE04`	Data Files Expired	Geocoder data files are expired. Please update with the latest data files.
`GE05`	License Not Enabled For Country	Geocoding for the country of input record is disabled for your License Key. Please contact your sales representative to enable.

Reference Guide

Contents

Reference Guide#