Reverse GeoCoder

Introduction

Reverse GeoCoder can:

• Create a mailing list within a specific radius for targeted marketing.

• Use in mobile apps for emergency location purposes & provide roadside help.

• Identify the closest valid address(es) based on an input latitude and longitude

• Provide the closest Postal Code(s), Carrier Route(s) or Plus4(s) based on an input latitude and longitude.

• Create a dealer locator: Provide the closest valid address, Melissa Address Key (MAK) and distance from a provided list of MAKs based on an input latitude and longitude or MAK.

Click here to learn more about the Reverse GeoCoder Cloud API.

Licensing

The License Key is a software key required to use the web service. You will receive your license key from your Melissa representative. If you don’t have a license key, contact the Melissa sales team at Sales@Melissa.com or 800-MELISSA ext. 3 (800-635-4772 ext. 3). Without a license key, Reverse GeoCoder will not function.

Initialization

There are two different constructors that you can utilize when initializing Reverse GeoCoder.

ReverseGeoCoder(string license)

Initialize the Cloud API object with a license key

Note

MELISSA_LICENSE_KEY is replaced with your license.

Get your license key here

• C#
• Python

ReverseGeoCoder reverseGeoCoder = new ReverseGeoCoder(MELISSA_LICENSE_KEY);

reverse_geo_coder = ReverseGeoCoder(MELISSA_LICENSE_KEY)

ReverseGeoCoder()

Initialize the Cloud API object, which will read the license key from the environment variable MD_LICENSE or configured using a set method

Click here to learn more about setting up the environment variable.

• C#
• Python

ReverseGeoCoder reverseGeoCoder = new ReverseGeoCoder()

reverse_geo_coder = ReverseGeoCoder()

Configuration

Reverse GeoCoder supports both GET and POST requests.

• (GET) Using one of three ways to configure each respective parameter

• (POST) Using the Set Post Body Method to pass a ReverseGeoCoderPostRequest object as the pre-constructed post body containing all parameters and records to process

Requests

GET

To send a GET request, there are three ways you can configure the parameters to make a request.

• Method 1: Using the Set Value Method to specify the parameter and value you want to set it to

• Method 2: Using direct property access to set parameter values

• Method 3: Using specialized Set Methods to set parameter values

Method 1: Using Set Value Method

This function allows you to specify input parameters and the values you went to set them to.

Format

Note

Replace LATITUDE, LONGITUDE, and MAX_RECORDS with variables or values.

• C#
• Python

reverseGeoCoder.SetValue("Latitude", LATITUDE);
reverseGeoCoder.SetValue("Longitude", LONGITUDE);
reverseGeoCoder.SetValue("MaxRecords", MAX_RECORDS);

reverse_geo_coder.set_value("latitude", LATITUDE)
reverse_geo_coder.set_value("longitude", LONGITUDE)
reverse_geo_coder.set_value("max_records", MAX_RECORDS)

Example

• C#
• Python

reverseGeoCoder.SetValue("Latitude", "33.637520");
reverseGeoCoder.SetValue("Longitude", "-117.606920");
reverseGeoCoder.SetValue("MaxRecords", "3");

reverse_geo_coder.set_value("latitude", "33.637520")
reverse_geo_coder.set_value("longitude", "-117.606920")
reverse_geo_coder.set_value("max_records", "3")

Method 2: Using Direct Property Access

This allows you to set values directly using the Cloud API’s parameter names.

Format

Note

Replace LATITUDE, LONGITUDE, and MAX_RECORDS with variables or values.

• C#
• Python

reverseGeoCoder.Latitude = LATITUDE;
reverseGeoCoder.Longitude = LONGITUDE;
reverseGeoCoder.MaxRecords = MAX_RECORDS;

reverse_geo_coder.latitude = LATITUDE
reverse_geo_coder.longitude = LONGITUDE
reverse_geo_coder.max_records = MAX_RECORDS

Example

• C#
• Python

reverseGeoCoder.Latitude = "33.637520";
reverseGeoCoder.Longitude = "-117.606920";
reverseGeoCoder.MaxRecords = "3";

reverse_geo_coder.latitude = "33.637520"
reverse_geo_coder.longitude = "-117.606920"
reverse_geo_coder.max_records = "3"

Method 3: Using Specialized Methods

These functions allow you to set the input parameters for the Cloud API.

See Set Methods for a list of available parameters.

Format

Note

Replace LATITUDE, LONGITUDE, and MAX_RECORDS with variables or values.

• C#
• Python

reverseGeoCoder.SetLatitude(LATITUDE);
reverseGeoCoder.SetLongitude(LONGITUDE);
reverseGeoCoder.SetMaxRecords(MAX_RECORDS);

reverse_geo_coder.set_latitude(LATITUDE)
reverse_geo_coder.set_longitude(LONGITUDE)
reverse_geo_coder.set_max_records(MAX_RECORDS)

Example

• C#
• Python

reverseGeoCoder.SetLatitude("33.637520");
reverseGeoCoder.SetLongitude("-117.606920");
reverseGeoCoder.SetMaxRecords("3");

reverse_geo_coder.set_latitude("33.637520")
reverse_geo_coder.set_longitude("-117.606920")
reverse_geo_coder.set_max_records("3")

POST

To send a POST request, there is one way you can configure the parameters to make a request.

• Method 1: Using the Set Post Body Method to pass a ReverseGeoCoderPostRequest object as the pre-constructed post body containing all parameters and records to process

Method 1: Set Post Body

This function allows you to pass a pre-constructed post body with all parameters and records for POST requests.

Format

Note

Replace MELISSA_LICENSE_KEY, LATITUDE, LONGITUDE, and MAX_RECORDS with variables or values.

Get your license key here

• C#
• Python

reverseGeoCoder.SetPostBody(new ReverseGeoCoderRecordRequest
{
    CustomerId = MELISSA_LICENSE_KEY,
    Latitude = LATITUDE,
    Longitude = LONGITUDE,
    MaxRecords = MAX_RECORDS
});

reverse_geo_coder.set_post_body(ReverseGeoCoderRecordRequest(
    customer_id = MELISSA_LICENSE_KEY,
    latitude = LATITUDE,
    longitude = LONGITUDE,
    max_records = MAX_RECORDS
))

Example

Note

MELISSA_LICENSE_KEY is replaced with your license.

Get your license key here

• C#
• Python

reverseGeoCoder.SetPostBody(new ReverseGeoCoderRecordRequest
{
    CustomerId = MELISSA_LICENSE_KEY,
    Latitude = "33.63756710910554",
    Longitude = "-117.60695049134513",
    MaxRecords = "2"
});

reverse_geo_coder.set_post_body(ReverseGeoCoderRecordRequest(
    customer_id = MELISSA_LICENSE_KEY,
    latitude = "33.63756710910554",
    longitude = "-117.60695049134513",
    max_records = "2"
))

Response

When submitting a request, you have the option to either get the response as a string or encapsulate the response into the respective Cloud API response object.

As a String

Submit a GET or POST request and get the response as a string.

• C#
• Python

string response = reverseGeoCoder.GetDoLookup<string>();

response = reverse_geo_coder.get_do_lookup(str)

• C#
• Python

string response = reverseGeoCoder.PostDoLookup<string>();

response = reverse_geo_coder.post_do_lookup(str)

As a Response Object

Submit a GET or POST request and encapsulate the response into the Cloud API response object.

• C#
• Python

ReverseGeoCoderResponse responseObject = reverseGeoCoder.GetDoLookup<ReverseGeoCoderResponse>();

response = reverse_geo_coder.get_do_lookup(ReverseGeoCoderResponse)

• C#
• Python

ReverseGeoCoderResponse responseObject = reverseGeoCoder.PostDoLookup<ReverseGeoCoderResponse>();

response = reverse_geo_coder.post_do_lookup(ReverseGeoCoderResponse)

Accessing Values

When encapsulating the response into the Cloud API’s respective response object, there are three ways to access values. The response object structure matches the respective Cloud API’s response format.

Click here to learn more about the Reverse GeoCoder response format.

The record responses are typically stored in a list. In the examples below, record represents an individual record at an arbitrary position within this list.

1. Using the Get Value Method:

Pass the field name as a string to the Get Value Method, and it will return the corresponding field value.

• C#
• Python

record.GetValue("RecordID");
record.GetValue("Results");

record.get_value("RecordID")
record.get_value("Results")

2. Accessing Properties directly

Values can be accessed directly using the response object’s field names.

• C#
• Python

record.RecordID;
record.Results;

record.record_id
record.results

3. Use Specialized Methods

Use get methods corresponding to field name to get the field value.

• C#
• Python

record.GetRecordID();
record.GetResults();

record.get_record_id()
record.get_results()

Methods

The methods listed below pertain to the Reverse GeoCoder API object.

For methods related to the respective Cloud API’s response object click here.

Constructors

These methods initialize and configure instances of the Cloud API object. Use these methods to create a new object, optionally providing initial values such as a license string to customize the instance during its creation.

• C#
• Python

Method	Description
ReverseGeoCoder()	Constructor to initialize the Reverse GeoCoder object.
ReverseGeoCoder(string license)	Constructor to initialize the Reverse GeoCoder object with a license string.

Method	Description
ReverseGeoCoder()	Constructor to initialize the Reverse GeoCoder object.
ReverseGeoCoder(license)	Constructor to initialize the Reverse GeoCoder object with a license string.

Set Methods

These methods configure or modify parameters at the record level for the Cloud API object. Use these methods to make adjustments to the parameters during the execution of the Cloud API, ensuring flexibility in customizing API requests.

• C#
• Python

Method	Description
void SetBaseUrl(string baseUrl)	Set the base URL.
void SetLicense(string license)	Set the license string.
void SetEndpoint(string endpoint)	Set the endpoint.
void SetFormat(string format)	Set the format.
void SetLatitude(string latitude)	Set the latitude.
void SetLongitude(string longitude)	Set the longitude.
void SetMaxRecords(string records)	Set the max records.
void SetMaxDistance(string distance)	Set the max distance.
void SetTransmissionReference(string transmissionReference)	Set the transmission reference.
void SetOpt(string opt)	Set the option.
void SetValue(string parameter, string value)	Set the input parameter to a specified value.
void SetPostBody(ReverseGeoCoderRecordRequest postBody)	Set the post body for post requests.

Method	Description
set_base_url(base_url)	Set the base URL.
set_license(license)	Set the license string.
set_endpoint(endpoint)	Set the endpoint.
set_format(format)	Set the format.
set_latitude(latitude)	Set the latitude.
set_longitude(longitude)	Set the longitude.
set_max_records(records)	Set the max records.
set_max_distance(distance)	Set the max distance.
set_transmission_reference(transmission_reference)	Set the transmission reference.
set_opt(opt)	Set the option.
set_value(parameter, value)	Set the input parameter to a specified value.
set_post_body(post_body)	Set the post body for post requests.

Get Methods

These methods retrieve parameter values from the Cloud API object. Use these methods to access the parameters configured for the Cloud API at the record level, providing insight into the current state of the object’s settings.

• C#
• Python

Method	Description
string GetBaseUrl()	Get the base URL.
string GetLicense()	Get the license string.
string GetEndpoint()	Get the endpoint.
string GetFormat()	Get the format.
string GetLatitude()	Get the latitude.
string GetLongitude()	Get the longitude.
string GetMaxRecords()	Get the max records.
string GetMaxDistance()	Get the max distance.
string GetTransmissionReference()	Get the transmission reference.
string GetOpt()	Get the option.
void GetValue(string parameter)	Get the value of an input parameter.
ReverseGeoCoderRecordRequest GetPostBody()	Get the post body for post requests.

Method	Description
get_base_url()	Get the base URL.
get_license()	Get the license string.
get_endpoint()	Get the endpoint.
get_format()	Get the format.
get_latitude()	Get the latitude.
get_longitude()	Get the longitude.
get_max_records()	Get the max records.
get_max_distance()	Get the max distance.
get_transmission_reference()	Get the transmission reference.
get_opt()	Get the option.
get_value(parameter)	Get the value of an input parameter.
get_post_body()	Get the post body for post requests.

Class Methods

These methods perform service-level operations, handling the core processing and interactions for the Cloud API object. Use these methods to execute primary functionalities such as assembling records, clearing records, and making API requests.

• C#
• Python

Method	Description
T GetDoLookup<T>()	Endpoint: /v3/web/ReverseGeoCode/doLookup Makes the synchronous GET request to the CloudAPI and returns the response (string or deserialized response object).
async Task<T> GetDoLookupAsync<T>()	Endpoint: /v3/web/ReverseGeoCode/doLookup Makes the asynchronous GET request to the CloudAPI and returns the response.
T PostDoLookup<T>()	Endpoint: /v3/web/ReverseGeoCode/doLookup Makes a synchronous POST request to the CloudAPI using the post body and returns the response.
async Task<T> PostDoLookupAsync<T>()	Endpoint: /v3/web/ReverseGeoCode/doLookup Makes an asynchronous POST request to the CloudAPI using the post body and returns the response.
T GetDoLookupPostalCodes<T>()	Endpoint: /v3/web/ReverseGeoCode/doLookupPostalCodes Makes a synchronous GET request to the CloudAPI and returns the response.
async Task<T> GetDoLookupPostalCodesAsync<T>()	Endpoint: /v3/web/ReverseGeoCode/doLookupPostalCodes Makes an asynchronous GET request to the CloudAPI and returns the response.
T PostDoLookupPostalCodes<T>()	Endpoint: /v3/web/ReverseGeoCode/doLookupPostalCodes Makes a synchronous POST request to the CloudAPI using the post body and returns the response.
async Task<T> PostDoLookupPostalCodesAsync<T>()	Endpoint: /v3/web/ReverseGeoCode/doLookupPostalCodes Makes an asynchronous POST request to the CloudAPI using the post body and returns the response.
string GetApiVersion()	Makes a synchronous getversion request and returns the parsed Cloud API version.
async Task<string> GetApiVersionAsync()	Makes an asynchronous getversion request and returns the parsed Cloud API version.

Method	Description
get_do_lookup(response_type)	Endpoint: /v3/web/ReverseGeoCode/doLookup Makes the synchronous GET request to the CloudAPI and returns the response.
get_do_lookup_async(response_type)	Endpoint: /v3/web/ReverseGeoCode/doLookup Makes the asynchronous GET request to the CloudAPI and returns the response.
post_do_lookup(response_type)	Endpoint: /v3/web/ReverseGeoCode/doLookup Makes a synchronous POST request to the CloudAPI using the post body and returns the response.
post_do_lookup_async(response_type)	Endpoint: /v3/web/ReverseGeoCode/doLookup Makes an asynchronous POST request to the CloudAPI using the post body and returns the response.
get_do_lookup_postal_codes(response_type)	Endpoint: /v3/web/ReverseGeoCode/doLookupPostalCodes Makes a synchronous GET request to the CloudAPI and returns the response.
get_do_lookup_postal_codes_async(response_type)	Endpoint: /v3/web/ReverseGeoCode/doLookupPostalCodes Makes an asynchronous GET request to the CloudAPI and returns the response.
post_do_lookup_postal_codes(response_type)	Endpoint: /v3/web/ReverseGeoCode/doLookupPostalCodes Makes a synchronous POST request to the CloudAPI using the post body and returns the response.
post_do_lookup_postal_codes_async(response_type)	Endpoint: /v3/web/ReverseGeoCode/doLookupPostalCodes Makes an asynchronous POST request to the CloudAPI using the post body and returns the response.
get_api_version()	Makes a synchronous getversion request and returns the parsed Cloud API version.
get_api_version_async()	Makes an asynchronous getversion request and returns the parsed Cloud API version.