Quickstart#
Introduction#
GeoCoder Object® enables you to access geographic data using your ZIP Code™ and optional Plus4. This allows you to obtain latitude and longitude geographic coordinates, census tract and block numbers, as well as county name and FIPS numbers.
Sample Code#
GeoCoder is compatible with multiple coding languages across different systems. The table below will link you to the sample code for each language hosted in the github repositories.
Language |
System |
Repository |
|---|---|---|
C# .NET |
Windows |
|
Linux |
||
C++ |
Windows |
|
Linux |
||
Java |
Windows |
|
Linux |
||
Python3 |
Windows |
|
Linux |
||
How To Get Data#
Use the Melissa Updater to download the data files using the manifest named geocoder_data.
Getting Started#
Basic Flow of Actions#
To use the GeoCoder Object, you can give it a license, data path, and ZIP code. It will then look up the ZIP code and store geographic information related to it. It can also return result codes based on what cases occured during the lookup.
This is the flow of how GeoCoder Object is usually implemented:
The Reference Guide goes into detail on every method available with the GeoCoder Object. All the Result Codes and descriptions are also in the reference guide.
1. Initialize GeoCoder Object#
Start by creating an instance of the Melissa GeoCoder Object.
Example Implementation:
// Create instance of Melissa GeoCoder Object
public mdGeo mdGeoObj = new mdGeo();
// Create instance of Melissa GeoCoder Object
mdGeo* mdGeoObj = new mdGeo;
// Create instance of Melissa GeoCoder Object
mdGeo mdGeoObj = new mdGeo();
# Create instance of Melissa GeoCoder Object
md_geo_obj = mdGeo_pythoncode.mdGeo()
2. Set a License#
To set a license, either configure the environmental variable for the license or use the method SetLicenseString.
Example Implementation:
// Set license string
mdGeoObj.SetLicenseString(MELISSA_LICENSE_STRING);
// Set license string
mdGeoObj->SetLicenseString(MELISSA_LICENSE_STRING.c_str());
// Set license string
mdGeoObj.SetLicenseString(MELISSA_LICENSE_STRING);
# Set license string
md_geo_obj.SetLicenseString(MELISSA_LICENSE_STRING)
To see when the license will expire, use the method GetLicenseExpirationDate.
Example Implementation:
mdGeoObj.GetLicenseExpirationDate();
mdGeoObj->GetLicenseExpirationDate();
mdGeoObj.GetLicenseExpirationDate();
md_geo_obj.GetLicenseExpirationDate()
3. Initialize Data Files#
To set the path for the data files, use the following methods:
To setup the data files, use the method InitializeDataFiles.
ProgramStatus can be used to store the result from InitializeDataFiles in order to ensure it worked as expected.
Example Implementation:
// Set data paths for objects
mdGeoObj.SetPathToGeoCodeDataFiles(PATH_TO_DATA_FILES);
mdGeoObj.SetPathToGeoCanadaDataFiles(PATH_TO_DATA_FILES);
mdGeoObj.SetPathToGeoPointDataFiles(PATH_TO_DATA_FILES);
mdGeo.ProgramStatus pStatus = mdGeoObj.InitializeDataFiles();
// Handle potential issues while initializing the data files
if (pStatus != mdGeo.ProgramStatus.ErrorNone)
{
Console.WriteLine("Fail to Initialize Object.");
Console.WriteLine(pStatus);
return;
}
// Set data paths for objects
mdGeoObj->SetPathToGeoCodeDataFiles(PATH_TO_DATA_FILES.c_str());
mdGeoObj->SetPathToGeoCanadaDataFiles(PATH_TO_DATA_FILES.c_str());
mdGeoObj->SetPathToGeoPointDataFiles(PATH_TO_DATA_FILES.c_str());
mdGeo::ProgramStatus pStatus = mdGeoObj->InitializeDataFiles();
if (pStatus != mdGeo::ProgramStatus::ErrorNone)
{
cout << "Failed to Initialize Object." << endl;
cout << pStatus << endl;
return;
}
// Set data paths for objects
mdGeoObj.SetPathToGeoCodeDataFiles(PATH_TO_DATA_FILES);
mdGeoObj.SetPathToGeoCanadaDataFiles(PATH_TO_DATA_FILES);
mdGeoObj.SetPathToGeoPointDataFiles(PATH_TO_DATA_FILES);
mdGeo.ProgramStatus pStatus = mdGeoObj.InitializeDataFiles();
if (pStatus != mdGeo.ProgramStatus.ErrorNone) {
// Problem during initialization
System.out.println("Failed to Initialize Object.");
System.out.println(pStatus);
return;
}
# Set data paths for objects
md_geo_obj.SetPathToGeoCodeDataFiles(PATH_TO_DATA_FILES)
md_geo_obj.SetPathToGeoCanadaDataFiles(PATH_TO_DATA_FILES)
md_geo_obj.SetPathToGeoPointDataFiles(PATH_TO_DATA_FILES)
p_status = md_geo_obj.InitializeDataFiles()
if (p_status != mdGeo_pythoncode.ProgramStatus.ErrorNone):
print("Failed to Initialize Object.")
print(p_status)
return
To check at what date the database was updated, use the method GetDatabaseDate.
To get the development build number of Global Address Object, use the method GetBuildNumber.
Example Implementation:
// If you see a different date than expected, check your license string and either
// download the new data files or use the Melissa Updater program to update your data files.
mdGeoObj.GetDatabaseDate();
// This number should match with file properties of the Melissa Object binary file.
// If TEST appears with the build number, there may be a license key issue.
mdGeoObj.GetBuildNumber();
// If you see a different date than expected, check your license string and either
// download the new data files or use the Melissa Updater program to update your data files.
mdGeoObj->GetDatabaseDate();
// This number should match with file properties of the Melissa Object binary file.
// If TEST appears with the build number, there may be a license key issue.
mdGeoObj->GetBuildNumber();
// If you see a different date than expected, check your license string and either
// download the new data files or use the Melissa Updater program to update your data files.
mdGeoObj.GetDatabaseDate();
// This number should match with file properties of the Melissa Object binary file.
// If TEST appears with the build number, there may be a license key issue.
mdGeoObj.GetBuildNumber();
# If you see a different date than expected, check your license string and either
# download the new data files or use the Melissa Updater program to update your data files.
md_geo_obj.GetDatabaseDate()
# This number should match with file properties of the Melissa Object binary file.
# If TEST appears with the build number, there may be a license key issue.
md_geo_obj.GetBuildNumber()
The method GetInitializeErrorString can get the status on errors in initialization. This can help determine if the code should continue running.
Example Implementation:
bool shouldContinueRunning = true;
if (mdGeoObj.GetInitializeErrorString() != "No error")
{
shouldContinueRunning = false;
}
bool shouldContinueRunning = true;
if (string(mdGeoObj->GetInitializeErrorString()) != "No error.")
{
shouldContinueRunning = false;
}
Boolean shouldContinueRunning = true;
if (!mdGeoObj.GetInitializeErrorString().equals("No error"))
shouldContinueRunning = false;
should_continue_running = True
if md_geo_obj.GetInitializeErrorString() != "No error":
should_continue_running = False
4. Lookup ZIP For Geographic Data#
The method SetInputParameter can set the ZIP code for lookup by giving it the parameter name “Zip” along with the corresponding ZIP value:
The method FindGeo can get the geo data associated with the ZIP code.
Example Implementation:
mdGeoObj.SetInputParameter("Zip", ZIP_STRING);
// This will call the function to process the input zip
// as well as generate the result codes
mdGeoObj.FindGeo();
mdGeoObj->SetInputParameter("Zip", ZIP_STRING);
// This will call the function to process the input zip
// as well as generate the result codes
mdGeoObj->FindGeo();
mdGeoObj.SetInputParameter("Zip", ZIP_STRING);
// This will call the function to process the input zip
// as well as generate the result codes
mdGeoObj.FindGeo();
md_geo_obj.SetInputParameter("Zip", ZIP_STRING)
# This will call the function to process the input zip
# as well as generate the result codes
md_geo_obj.FindGeo()
5. Get GeoCoder Object Information#
The following methods can get specific data fields from the GeoCode:
GetCountySubdivisionName
Example Implementation:
mdGeoObj.GetPlaceName();
mdGeoObj.GetCountyName();
mdGeoObj.GetCountySubdivisionName();
mdGeoObj.GetTimeZone();
mdGeoObj.GetLatitude();
mdGeoObj.GetLongitude();
mdGeoObj->GetPlaceName();
mdGeoObj->GetCountyName();
mdGeoObj->GetCountySubdivisionName();
mdGeoObj->GetTimeZone();
mdGeoObj->GetLatitude();
mdGeoObj->GetLongitude();
mdGeoObj.GetPlaceName();
mdGeoObj.GetCountyName();
mdGeoObj.GetCountySubdivisionName();
mdGeoObj.GetTimeZone();
mdGeoObj.GetLatitude();
mdGeoObj.GetLongitude();
md_geo_obj.GetPlaceName()
md_geo_obj.GetCountyName()
md_geo_obj.GetCountySubdivisionName()
md_geo_obj.GetTimeZone()
md_geo_obj.GetLatitude()
md_geo_obj.GetLongitude()
6. Get the Melissa Result Codes#
In order to grab the result codes, call the method GetResults. This will return all of the result codes stacked together in a single String separated by ‘,’ delimiters.
Example Implementation:
string ResultCodes = mdGeoObj.GetResults();
string ResultCodes = mdGeoObj->GetResults();
String ResultCodes = mdGeoObj.GetResults();
result_codes = md_geo_obj.GetResults()
The following implementation shows one way of interpreting the results by using the method GetResultCodeDescription:
mdGeoObj.GetResultCodeDescription(RESULT_CODE_STRING, mdGeo.ResultCdDescOpt.ResultCodeDescriptionLong);
// ResultsCodes explain any issues GeoCoder Object has.
mdGeoObj->GetResultCodeDescription(RESULT_CODE_STRING.c_str(), mdGeo->ResultCodeDescriptionLong);
// ResultsCodes explain any issues GeoCoder Object has.
mdGeoObj.GetResultCodeDescription(RESULT_CODE_STRING, mdGeo.ResultCdDescOpt.ResultCodeDescriptionLong);
// ResultsCodes explain any issues GeoCoder Object has.
md_geo_obj.GetResultCodeDescription(RESULT_CODE_STRING, mdGeo_pythoncode.ResultCdDescOpt.ResultCodeDescriptionLong)
# ResultsCodes explain any issues GeoCoder Object has.