Reverse GeoCoder:doLookup

← Reverse GeoCoder

Request

A request consists of a protocol to make a call to the service, detailing desired elements. The minimum required elements in a request are your License Key and at least one set of geo-coordinates.

Reverse GeoCoder supports multiple protocols to access the service, including JSON, REST, and XML.

URL

REST, XML, JSON, etc.

Use	URL
Standard	http://reversegeo.melissadata.net/v3/WEB/ReverseGeoCode/DoLookup
Secure	https://reversegeo.melissadata.net/v3/WEB/ReverseGeoCode/DoLookup

JSONP

Use	URL
Standard	http://reversegeo.melissadata.net/v3/jsonp/ReverseGeoCode/DoLookup
Secure	https://reversegeo.melissadata.net/v3/jsonp/ReverseGeoCode/DoLookup

Header

HTTP headers need to match the protocols and formats being used.

Reverse GeoCoder requires the values of Content-Type and Accept.

Example JSON Request Header

{
    "Content-Type": "application/json; charset=utf-8",
    "Accept": "application/json"
}

Field Names

This is a list of the request field names and their protocol naming conventions.

Field Name	Level	REST	JSON
Transmission Reference	Request	t	TransmissionReference
License Key		id	CustomerID
Latitude		lat	Latitude
Longitude		long	Longitude
MaxDistance		dist	MaxDistance
MaxRecords		recs	MaxRecords
Options		opt	Options
Format	format

Request Elements

The following elements set the basic options for each request. These apply to the entire request, not the individual records.

Transmission Reference

Optional.

This is a string value that serves as a unique identifier for this set of records. It is returned as sent.

Protocol	Syntax
JSON	"TransmissionReference":"string"
REST	?t = string
XML	<TransmissionReference>string</TransmissionReference>

License Key

Required.

This is a string value containing the License Key issued to you for this product.

If this element is absent, the Web Service will return an error. To receive a License Key, please contact your Melissa sales representative at 1-800-MELISSA.

Protocol	Syntax
JSON	"CustomerID":"string"
REST	&id = string
XML	<CustomerID>string</CustomerID>

Latitude

Required.

The latitude geographic coordinate in decimal format.

Protocol	Syntax
JSON	"Latitude":"string"
REST	&lat = string
XML	<Latitude>string</Latitude>

Longitude

Required.

The longitude geographic coordinate in decimal format.

Protocol	Syntax
JSON	"Longitude":"string"
REST	&long = string
XML	<Longitude>string</Longitude>

MaxDistance

Optional.

The requested maximum distance (in miles). The maximum possible distance is 10 miles. If no MaxDistance is specified, the default is 10 miles.

Protocol	Syntax
JSON	"MaxDistance":"string"
REST	&dist = string
XML	<MaxDistance>string</MaxDistance>

MaxRecords

Optional.

The requested number of records. The Maximum number of records the user can get is 100 records. This is also the default if no MaxRecords is specified.

Protocol	Syntax
JSON	"MaxRecords":"string"
REST	&recs = string
XML	<MaxRecords>string</MaxRecords>

Options

Optional.

This is a string value containing the options set by the user.

Protocol	Syntax
JSON	"Options":"string"
REST	?opt = string
XML	<Options>string</Options>

List options in the following format, with multiple options delimited with a ";".

Syntax
OptionName:Parameter;OptionName:Parameter

IncludeApartments

This options allows you to include records with a non-null baseMAK.

Option Name	Parameter	Description
IncludeApartments	Off	Default. Non-null baseMAK records are not included.
	On	Records with a non-null baseMAK will be included in your search.

IncludeUndeliverable

This options allows you to specify if you want to include addresses we have identified as unable to deliver mail to.

Option Name	Parameter	Description
IncludeUndeliverable	Off	Undeliverable addresses are not included.
	On	Default. Undeliverable addresses are included in your search.

IncludeEmptyLots

This options allows you to specify if you want to include addresses that are empty lots in your search.

Option Name	Parameter	Description
IncludeEmptyLots	Off	Default. Empty lots are not included.
	On	Empty lots are included in your search.

Format

Optional.

The desired format of the response. Possible values for this option are "json" or "xml". The default value is "xml".

Protocol	Syntax
REST	&format = string

Response

A response is the result of a request. This consists of returned results codes and returned addresses, depending on the input provided.

Depending on the protocol used to make the request, the response will be in a certain protocol. Reverse GeoCoder supports these response protocols: XML, and JSON.

Field Names

This is a list of the response field names and their protocol naming conventions.

Field Name	Level	JSON/XML
Version	Response (Base)	Version
Transmission Reference		TransmissionReference
Transmission Results		TransmissionResults
Results		Results
Total Records		TotalRecords
Records	Record	Records
Address Line 1		AddressLine1
Suite Name		SuiteName
Suite Count		SuiteCount
City		City
State		State
Postal Code		PostalCode
AddressKey		AddressKey
Latitude		Latitude
Longitude		Longitude
Distance		Distance

Response Elements

The following elements are the basic options for each request. These apply to the entire response, not the individual records.

Version

This is a string value that is the current revision number of Reverse GeoCoder.

Protocol	Syntax
JSON	"Version":"string"
XML	<Version>string</Version>

Transmission Reference

This is a string value that serves as a unique identifier for this set of records. It is returned as sent by the Request Array, allowing you to match the Response to the Request.

Protocol	Syntax
JSON	"TransmissionReference":"string"
XML	<TransmissionReference>string</TransmissionReference>

Transmission Results

This is a string value that lists error codes from any errors caused by the most recent request as a whole.

For a complete list of error codes, see Reverse GeoCoder Result Codes.

Protocol	Syntax
JSON	"TransmissionResults":"string"
XML	<TransmissionResults>string</TransmissionResults>

Results

This is a string value with comma delimited status, error codes, and change codes for the record.

For a complete list of error codes, see Reverse GeoCoder Result Codes.

Protocol	Syntax
JSON	"Results":"string"
XML	<Results>string</Results>

Total Records

Displays the total number of records returned.

Protocol	Syntax
JSON	"TotalRecords":"string"
XML	<TotalRecords>string</TotalRecords>

Response Record Elements

JSON will only contain the Records element.

Protocol	Definition
JSON	Each record will be contained within [{}] under the Records element.
XML

Each of the following elements are returned for each record in the Response Array.

AddressLine1

Returns the street address (street number and street name) that corresponds to the input geo coordinates.

Protocol	Syntax
JSON	"AddressLine1":"string"
XML	<AddressLine1>string</AddressLine1>

SuiteName

Returns the suite name of the address returned. Values that could be returned are: Ste, Apt., etc.

Protocol	Syntax
JSON	"SuiteName":"string"
XML	<SuiteName>string</SuiteName>

SuiteCount

Returns the number of suites in a particular building. Zero will be returned if the address has a no suites (a single delivery point).

Protocol	Syntax
JSON	"SuiteCount":"string"
XML	<SuiteCount>string</SuiteCount>

City

Returns the city of the output address.

Protocol	Syntax
JSON	"City":"string"
XML	<City>string</City>

State

Returns the State of the output address.

Protocol	Syntax
JSON	"State":"string"
XML	<State>string</State>

PostalCode

Returns the Postal Code of the output address.

Protocol	Syntax
JSON	"PostalCode":"string"
XML	<PostalCode>string</PostalCode>

AddressKey

Returns a unique identifier for an address. This key can be used with other current and future Melissa Data services.

Protocol	Syntax
JSON	"AddressKey":"string"
XML	<AddressKey>string</AddressKey>

Latitude

Returns the latitude geographic coordinate of the output address.

Protocol	Syntax
JSON	"Latitude":"string"
XML	<Latitude>string</Latitude>

Longitude

Returns the longitude geographic coordinate of the output address.

Protocol	Syntax
JSON	"Longitude":"string"
XML	<Longitude>string</Longitude>

Distance

Returns the distance between the input coordinates and the output coordinates. A distance of zero indicates that an exact address match was returned for the input geographic coordinates.

Protocol	Syntax
JSON	"Distance":"string"
XML	<Distance>string</Distance>

MelissaAddressKey

Returns the Melissa Address Key (MAK). 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. Melissa Address Key (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.

Protocol	Syntax
JSON	"MelissaAddressKey":"string"
XML	<MelissaAddressKey>string</MelissaAddressKey>

MelissaAddressKeyBase

Returns the Melissa Address Key Base (BaseMAK). Every full address has its own Melissa Address Key (MAK). If that address is a suites or apartment, we will also return a Melissa Address Key Base (BaseMAK) that corresponds to the overall building. This provides a link between all the individual MAK addresses that belong to the same building. This field also returns a 10-digit proprietary key. Note, if we can validate the address to the building but not the suite, we can return just the BaseMAK.

Protocol	Syntax
JSON	"MelissaAddressKeyBase":"string"
XML	<MelissaAddressKeyBase>string</MelissaAddressKeyBase>