Reference Guide

GeoCoder Object

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.

Minimum System Requirements

The GeoCoder Object has the following system requirements:

Hardware	Detail
HDD	1GB Hard Disk Space

Operating System	Details
Windows	Windows 7 or later personal computer OS version. Windows Server 2008 R2 or later Windows Server version.
Linux	Linux distribution supporting GCC 3.3 or GCC 4.1.
Solaris	Solaris 8.0 and newer supporting Workshop6 compiler or Workshop 12.
AIX	AIX 5.2 supporting XLC6 and AIX 7 supporting GCC 8.3
HP-UX	Version 11 or later supporting ACC3 or GCC 3.4

Installation

To install GeoCoder Object you need to close all open applications, including any anti-virus and e-mail software.
Download the zip file from the link you received in your email.
Unzip the file and run the setup file for your operating system.

Operating System	Install File Name
Windows	setup.exe
Unix	setup.sh

Read the license agreement, and then click Yes if you agree to the terms. (To proceed with the installation, you must accept this agreement.)
Select the option(s) that you want to install.
Verify the install location and selected options.
Click Install.
Verify the installation and clean up the download file if you need hard disk space.

Authentication

Melissa requires a License Key to access the full features of GeoCoder Object. Your License Key will be sent to you from your Melissa representative. Without the License Key, GeoCoder Object will not run.

Your license key will determine what functionality you have access to and your valid subscription dates are. Once a license key expires, your application using GeoCoder Object will no longer work. This is why it is important to make sure you keep your license up to date. Your Melissa representative will work with you closely to make sure you have time to renew your subscription and update your license.

GeoCoder Interface

Use GeoCoder Object to add geographic coordinate data to your addresses, segment and enhance your target marketing with official census information, plus append information like school districts.

Use the latitude and longitude from GeoCoder Object to locate the dealers closest to the customer.
Use the census FIPS, tract or block information to group customers by neighborhoods or county. Link census information to census demographics.
Determine direction and distance between two locations using the GeoCoder Object’s built-in functions.

GeoCoder Obejct's data set is updated quarterly.

Using the Interface

Make sure to first set up the GeoCoder Object before you continue below.

To use the GeoCoder Object, we've grouped the functions in order of use. Follow the steps below to use GeoCoder Object:

Initialization: Prepare the instance for processing
Set Inputs: Pass the data for geocoding
GeoCoding: Retrieve geographic data for multiple attributes
Get Results: Review the status of the verification
Get Output: Retrieve geocoded data

The rest of this document will walk you through these different steps and expand on their implementation and use.

!> What Census Data do you use?

Melissa makes up to three different sets of Census data available. The regular census output fields like CensusFIPS, CensusTrack, CensusBlock return the laest census data available. This is typically the latest ACS data.

You can also access the 2010 and 2020 CensusKeys (which are the concatenated fips, track and block values) using CensusKey2010 and CensusKey2020.

Initialization

Prepare Geocoder Object for use by pointing it to the location of your data files and setting your license. Initiazation is a resource intensive process, but only needs to be done once per instance. After an object is Initialized, it can continue to process inputs continually.

Instantiate

You have to first instantiate the GeoCoder Interface in your application code.

Set Your License

You can set your license in two ways:

Set Data Path

Once you've set your license, set the data file path with SetPathToGeoPointDataFiles. There is a single data file for GeoCoder Object: mdGeoCode.db3.

SetPathToGeoPointDataFiles

Initialize

Once you set the data file path you need to initialize and load it to ensure everything is working. Call InitializeDataFiles. If it returns anything other than 0 the initialization has failed and you need to check the return value of GetInitializeErrorString to find out why it failed. It's important to do this step since the data file is integral to the functionality of GeoCoder Object.

InitializeDataFiles
GetInitializeErrorString

Product Information Methods

Time is an eternal constant, so things will get old and expire... like your data file. If you want GeoCoder Object to work, be sure to use these methods to check the dates of the database and the build number of the object.

GetBuildNumber
GetDatabaseDate
GetExpirationDate
GetLicenseExpirationDate

_ GeoCoder Initialization

//Initialize GeoCoder Interface
SET addPtr = NEW instance of GeoCoder

//Set Data File path
CALL SetPathToGeoPointDataFiles WITH DataPath

//Initialize Data File and check for errors
CALL InitializeDataFiles RETURNING result
IF result <> 0 THEN
CALL GetInitializeErrorString RETURN ErrorMessage
DISPLAY ErrorMessage
ELSE
GeoCode Addresses
END IF

!> Environment Variable Alternative

The environment variable method of setting the license will override the value entered into SetLicenseString() via code. The environment variable method is the recommended method as it can be easily changed without re-compiling. When your current subscription expires and you renew, you will be issued a new license string.

!> Data File Updates

The GeoCoder Object data file is updated quarterly and you'll need at least 20GB of Hard Disk space for this file.

!> Weren't there More Data Files?

There were. Now there aren't. The new, improved and single data file is mdGeoCode.db3. This also means the SetPathToGeoCanadaDataFiles method has been deprecated. See the Deprecated section in the Appendix.

!> Database Dates

Make sure you call the GET database date methods AFTER you initialize the data file and told the object where to find the data files. Otherwise you'll get crazy dates that help absolutely no one... like 1969 or 1899.

Set Inputs

This method sets the input data in key-value pairs, in preparation for the FindGeo method.

`SetInputParameter`

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

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

Significance	Key String	Desscription
1	MAK	A proprietary Melissa unique key identifier for an address. This is derived from Address Checking.
2	Zip	The 5-digit postal code. You would set this for addresses that do not verify and therefore do not have a MAK number. You cannot get rooftop level geocoding but can still get Zip or Zip+4 level geocoding if you set this value.
3	Plus4	The 4-digit plus4 of the postal code. You would set this for addresses that do not verify and therefore do not have a MAK number. You cannot get rooftop level geocoding but can still get Zip or Zip+4 level geocoding if you set this value.
*	AddressKey	An 11 digit key of the property. Based on the Zip5, Plus4 and two digit delivery code. *This is deprecated and for users who only have addresskey.

_ Set Inputs

//Set the Input data
IF MAK is provided
  CALL SetInputParameter WITH MAK, makValue
  CALL SetInputParameter WITH Zip, ZipValue
  IF Plus4 is provided
    CALL SetInputParameter WITH Plus4, Plus4Value

GeoCoding

These methods retrieve the geographic data for multiple attributes. The main method you'll use here is FindGeo after your MAK, Zip and Plus4 inputs are set. Other methods are provided under Compute Methods for more specific use cases.

`FindGeo`

This method performs a lookup on the input data. Even though it's simple, it'll be your daily driver so get used to it.

_ GeoCode

//GeoCode the input data
CALL FindGeo

Get Results

Retrieve Status and Return Codes

`GetResults`

This returns a comma-delimited string of four-character codes that detail the status and any errors for the current record. For a general primer on Result Codes, please visit: Quickstart Result Codes.

For a list of all possible codes, visit: Melissa GeoCoder Object Wiki - Result Code Details

`GetResultCodeDescription`

This method returns a description of the input result code. It requires two values, a result code and an enumerated option. The options are as follows:

0 - ResultCodeDescriptionLong - Returns a detailed description of the input result code.
1 - ResultCodeDescriptionShort - Returns a short description of the input result code.

!> GetResults

For Example:

GS01, GE04, GW01

_ GeoCoded Data Handling

IF ResultsCode CONTAINS "GS01", "GS02", "GS03", "GS05", OR "GS06" THEN
{
//Handle GeoCoded Data
}
ELSE
{
//Return result code
}

!> Multifarious Enumeration

If a string of result codes are sent to GetResultCodeDescription, only the first result code will be used.

Get Outputs

Retrieve GeoCoded Data

`GetOutputParameter`

This returns the requested element geocoded by FindGeo. The available element strings are listed below. This method must be called after FindGeo.

Element String	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`	The latest available 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. The CensusKey of the latest Decennial census value. Will change once a new decennial census is available.
`CensusKey2010`	CensusKey for the 2010 Decennial Census.
`CensusKey2020`	CensusKey for the 2020 Decennial Census.
`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.
`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.

_ Get Outputs

//Handling GeoCoded Data
CALL GetOutputParameter(CountyName) RETURNING CountyName
CALL GetOutputParameter(CountyFIPSCode) RETURNING CountyFIPSCode
CALL GetOutputParameter(CensusBlock) RETURNING CensusBlock
CALL GetOutputParameter(CensusTract) RETURNING CensusTract
CALL GetOutputParameter(Latitude) RETURNING Latitude
CALL GetOutputParameter(Longitude) RETURNING Longitude
CALL GetOutputParameter(PlaceCode) RETURNING PlaceCode
CALL GetOutputParameter(PlaceName) RETURNING PlaceName
CALL GetOutputParameter(CBSACode) RETURNING CBSACode
CALL GetOutputParameter(CBSALevel) RETURNING CBSALevel
CALL GetOutputParameter(CBSATitle) RETURNING CBSATitle
CALL GetOutputParameter(CBSADivisionCode) RETURNING CBSADivisionCode
CALL GetOutputParameter(CBSADivisionLevel) RETURNING CBSADivisionLevel
CALL GetOutputParameter(CBSADivisionTitle) RETURNING CBSADivisionTitle
CALL GetOutputParameter(TimeZone) RETURNING TimeZone
CALL GetOutputParameter(TimeZoneCode) RETURNING TimeZoneCode

!> Empty Output Parameter?

If GetOutputParameter returns an empty string, it means you didn't first call FindGeo. Go back, call FindGeo first, then try this again.

Royalty Logging

In order to provide detailed and up to date geocoding information to you at an affordable price, we are obligated to log royalties for our data providers in certain scenarios:

Internet Logging

For smaller subscription levels, we are required to turn on internet logging. The Geocoder Object will reach out to Melissa servers for authentication and log the number of records processed. We have built mechanisms to reduce internet traffic, handle intermittent outages, while maintaining our royalty obligations. If Geocoder Object fails to initialize but was working without any changes, it is likely that it is due to a failure to communicate with Melissa servers. If this happens, please check your network and firewall allows internet access to our API.

Manual Logging

For Medium subscription levels, we do not require internet logging but will still need quarterly royalty reports from the client. The client can product their own usage reports, or use these methods to assist in generating usage data:

SetLatitude
SetLongitude
WriteToLogFile

The SetLatitude or SetLongitude functions will prevent records previously coded with GeoCoder Object from being counted towards your overall usage. Any addresses with previously geocoded values that match these properties won't be counted against your total usage.

No Logging

For Enterprise subscriptions we do not require any royalty reporting.

!> What's in a Log File?

You have to call the WriteToLogFile method before the InitializeDataFiles method. You also need a valid path or the log file will be made in the current directory of the program.

Log File Schema

Compute Methods

These methods can be used with the latitude and longitude returned from GetOutputParameter to calculate distances and bearing between two records.

Both methods have the same input parameters (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.

`ComputeBearing`

This method returns a bearing of 0 to 360 degrees representing the compass direction from point 1 to point 2.

North is 0 degrees, East is 90, South is 180, and West is 270.

`ComputeDistance`

This method returns the distance (in miles) between two points based on the given latitudes and longitudes.

!> Invalid Lat or Long?

If you enter an invalid latitude or longitude into ComputeBearing OR ComputeDistance, a value of 999 will be returned. So don't get confused!

!> Directional Conversions

While using ComputeBearing, if you need to convert your bearing to an approximate compass direction, use the following table:

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

Glossary

These are common words you'll see when dealing with GeoCoder Object.

CBSA - "Core Based Statistical Area". This is a collective term for both metropolitan and micropolitan statistical areas, which are geographic entities defined by the OMB (U.S. Office of Management and Budget). These are for use by Federal statistical agencies in collecting, tabulating and publishing Federal statistics. A metro area has a core urban area of 50,000 or more population with a micro area containing a core urban area of at least 10,000 population but less than 50,000 population. Each of these areas contain at least one county, including the core urban area and any adjacent counties with a high degree of social and economic integration, as measured by commuting to work.
Interpolated Rooftop - These coordinates were computed using mathematical algorithms and street shape maps. While these coordinates are educated estimates, they should be quite accurate for the majority of the United States. There may be cases where the location of interpolated points is not very near the actual residence, mostly in rural areas with long streets and non-standard house numbering. However, these coordinates are still much more accurate than ZIP + 4 coordinates.
Latitude - 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.
License - This is the license key provided to you by your Melissa representative. It is required for the object to work.
Longitude - 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.
MAK - Melissa Address Key. This is a globally unique and persistent key for the location, even if parts of the address change. When an address is fully validated this field returns a 10-digit proprietary key for the address. With AddressKey (US and Canada only), if an address ZIP Code™ changes, the AddressKey would also change. MAK is independent and will not change. This makes MAK a good way to permanently identify and locate addresses. Once you have a MAK it can be used as an input in most Melissa services and thus is a good tool for deduping.
Result Codes - Each record in the response has a results field that contains a series of result codes that carry a tremendous amount of information about the output. The result codes are delimited by commas. One way we recommend using result codes is as a filter between good and bad records. Determine which codes indicate a good record for your purposes and then filter out all the records that are returned without those codes. A good simple example would be if good records are those that return an AS01, AS02, or AS03 code (these codes generally indicate a valid address record). When you process a number of records through the service you can then parse the output and filter out all of the records that do not return one of those codes in the results field.
Rooftop - These are the most accurate latitude and longitude available with coverage of approximately 105 million individual addresses.
ZIP Code™ - Zone Improvement Plan Code. ZIP Code™s designate delivery routes and areas. There are three main parts of the 5-digit ZIP Code™—the national area, the region or city, and the delivery area.
ZIP+4® - In 1983 the USPS® changed its ZIP Code™ system to include the new ZIP+4®. A ZIP+4® Code uses the basic five-digit code plus four additional digits to identify a small delivery segment such as a street, a city block, a group of apartments, or even an individual address that receives a high volume of mail. The ZIP+4® Code is not required and is usually calculated automatically when the mail is sorted and processed.

Appendix

Deprecated GeoCoder Methods

These methods have been deprecated and you should not use them. We are keeping them here just so you know what's up. But don't use them. You've been warned.

Deprecated Initialization Methods

These methods have been deprecated now that GeoCoder has combined all the data files into one and now uses InitializeDataFiles.

Initialize
SetPathToGeoCanadaDataFiles
SetPathToGeoPointDataFiles

Deprecated GeoCoding

These methods have been deprecated in favor of using FindGeo.

GeoCode
GetPoint

Deprecated Results

This method has been deprecated in favor of using GetResults.

GetErrorCode
GetStatusCode

Deprecated Outputs

These are additional outputs available in the object that have been deprecated in favor of using GetOutputParameter. They aren't needed anymore, but are here for backwards compatibility.

GetCBSACode
GetCBSADivisionCode
GetCBSADivisionLevel
GetCBSADivisionTitle
GetCBSALevel
GetCBSATitle
GetCensusBlock
GetCensusTract
GetCountyFips
GetCountyName
GetLatitude
GetLongitude
GetPlaceCode
GetPlaceName
GetTimeZone
GetTimeZoneCode