Reference Guide#
Introduction#
Welcome to the Reverse GeoCoder Service by Melissa. This service provides the closest valid address(s), based on an input latitude and longitude. You can set the distance from the input coordinates (to reduce the number of returned output addresses) and a maximum number of records to be returned by the service.
In addition to valid addresses, the service will also return location information and an AddressKey. The AddressKey can be used by other Melissa services to obtain additional information, such as RBDI (Residential/Business Delivery Indicator) or Property information.
Base URL#
https://reversegeo.melissadata.net
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.
To set the license key, use the id/LicenseKey property in your requests.
Endpoints#
/V3/WEB/ReverseGeoCode/doLookup#
The Reverse GeoCoder doLookup endpoint will lookup addresses by choosing the actions and options needed.
Try It Now#
curl -X GET "https://ReverseGeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookup?\
&dist="10"\
&format=JSON\
&id={{customerId}}\
&lat="33.63756710910554"\
&long="-117.60695049134513"\
&opt=\
&recs=\
&t=Test" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
curl -X POST "https://reversegeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookup" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"CustomerId": {{customerId}},
"Latitude": "33.63756710910554",
"Longitude": "-117.60695049134513",
"MaxDistance": "10",
"MaxRecords": "",
"Options": "",
"TransmissionReference": "Test"
}'
curl -X GET "https://ReverseGeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookup?\
&dist="10"\
&format=XML\
&id={{customerId}}\
&lat="33.63756710910554"\
&long="-117.60695049134513"\
&opt=\
&recs=\
&t=Test" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml"
curl -X POST "https://reversegeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookup" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
-d '<RequestArray>
<CustomerId>{{customerId}}</CustomerId>
<Latitude>33.63756710910554</Latitude>
<Longitude>-117.60695049134513</Longitude>
<MaxDistance>10</MaxDistance>
<MaxRecords></MaxRecords>
<Options></Options>
<TransmissionReference>Test</TransmissionReference>
</RequestArray>'
Request Parameters#
Code |
Description |
||||
---|---|---|---|---|---|
Request Level Parameters |
|||||
|
The requested maximum distance in miles. The maximum value is |
||||
|
The License Key issued by Melissa. |
||||
|
The desired format of the response. Accepts |
||||
|
The latitude geographic coordinate in decimal format. |
||||
|
The longitude geographic coordinate in decimal format. |
||||
|
|||||
|
The requested number of records. The maximum value is |
||||
|
Optional. Serves as a unique request identifier. |
Code |
Description |
||||
---|---|---|---|---|---|
Request Level Parameters |
|||||
|
The License Key issued by Melissa. |
||||
|
The latitude geographic coordinate in decimal format. |
||||
|
The longitude geographic coordinate in decimal format. |
||||
|
The requested maximum distance in miles. The maximum value is |
||||
|
The requested number of records. The maximum value is |
||||
|
|||||
|
Optional. Serves as a unique request identifier. |
Code |
Description |
||||
---|---|---|---|---|---|
Request Level Parameters |
|||||
|
The requested maximum distance in miles. The maximum value is |
||||
|
The License Key issued by Melissa. |
||||
|
The desired format of the response. Accepts |
||||
|
The latitude geographic coordinate in decimal format. |
||||
|
The longitude geographic coordinate in decimal format. |
||||
|
|||||
|
The requested number of records. The maximum value is |
||||
|
Optional. Serves as a unique request identifier. |
Code |
Description |
||||
---|---|---|---|---|---|
Request Level Parameters |
|||||
|
The License Key issued by Melissa. |
||||
|
The latitude geographic coordinate in decimal format. |
||||
|
The longitude geographic coordinate in decimal format. |
||||
|
The requested maximum distance in miles. The maximum value is |
||||
|
The requested number of records. The maximum value is |
||||
|
|||||
|
Optional. Serves as a unique request identifier. |
Options#
List options in the following format, with multiple options delimited with a ,
.
OptionName:Parameter,OptionName:Parameter
IncludeApartments#
This options allows you to include records with a non-null baseMAK.
Default of Off
will not include non-null basekMAK records.
Parameter |
Description |
---|---|
|
Include apartments. |
|
Default. Do not include apartments. |
IncludeEmptyLots#
This options allows you to specify if you want to include addresses that are empty lots in your search.
Parameter |
Description |
---|---|
|
Include empty lots. |
|
Default. Do not include empty lots. |
IncludeUndeliverable#
This options allows you to specify if you want to include addresses we have identified as unable to deliver mail to.
Default of Off
will not include undeliverable addresses.
Parameter |
Description |
---|---|
|
Default. Include undeliverable addresses. |
|
Do not include undeliverable addresses. |
Headers#
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json
Content-Type: application/xml
Accept: application/xml
Content-Type: application/xml
Accept: application/xml
Response#
{
"Version": "6.2.0.5179",
"TransmissionReference": "",
"TransmissionResults": "",
"Results": "GS07",
"TotalRecords": 1,
"Records":
[{
"AddressLine1": "22382 Avenida Empresa",
"SuiteName": "",
"SuiteCount": "0",
"City": "Rancho Santa Margarita",
"State": "CA",
"PostalCode": "92688",
"AddressKey": "92688211282",
"Latitude": "33.637562",
"Longitude": "-117.606887",
"Distance": "0.003677",
"MelissaAddressKey": "8008006245",
"MelissaAddressKeyBase": "0"
}]
}
{
"Version": "6.2.0.5179",
"TransmissionReference": "",
"TransmissionResults": "",
"Results": "GS07",
"TotalRecords": 1,
"Records":
[{
"AddressLine1": "22382 Avenida Empresa",
"SuiteName": "",
"SuiteCount": "0",
"City": "Rancho Santa Margarita",
"State": "CA",
"PostalCode": "92688",
"AddressKey": "92688211282",
"Latitude": "33.637562",
"Longitude": "-117.606887",
"Distance": "0.003677",
"MelissaAddressKey": "8008006245",
"MelissaAddressKeyBase": "0"
}]
}
<ResponseArray
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="urn:mdReverseGeoCode">
<Version>6.2.0.5179</Version>
<TransmissionReference />
<TransmissionResults />
<Results>GS07</Results>
<TotalRecords>1</TotalRecords>
<Records>
<ResponseRecord>
<AddressLine1>22382 Avenida Empresa</AddressLine1>
<SuiteName />
<SuiteCount>0</SuiteCount>
<City>Rancho Santa Margarita</City>
<State>CA</State>
<PostalCode>92688</PostalCode>
<AddressKey>92688211282</AddressKey>
<Latitude>33.637562</Latitude>
<Longitude>-117.606887</Longitude>
<Distance>0.003677</Distance>
<MelissaAddressKey>8008006245</MelissaAddressKey>
<MelissaAddressKeyBase>0</MelissaAddressKeyBase>
</ResponseRecord>
</Records>
</ResponseArray>
<ResponseArray
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="urn:mdReverseGeoCode">
<Version>6.2.0.5179</Version>
<TransmissionReference />
<TransmissionResults />
<Results>GS07</Results>
<TotalRecords>1</TotalRecords>
<Records>
<ResponseRecord>
<AddressLine1>22382 Avenida Empresa</AddressLine1>
<SuiteName />
<SuiteCount>0</SuiteCount>
<City>Rancho Santa Margarita</City>
<State>CA</State>
<PostalCode>92688</PostalCode>
<AddressKey>92688211282</AddressKey>
<Latitude>33.637562</Latitude>
<Longitude>-117.606887</Longitude>
<Distance>0.003677</Distance>
<MelissaAddressKey>8008006245</MelissaAddressKey>
<MelissaAddressKeyBase>0</MelissaAddressKeyBase>
</ResponseRecord>
</Records>
</ResponseArray>
Service Level Response Fields#
Output Name |
Description |
---|---|
TotalRecords |
The current service version number. |
TransmissionReference |
A pass-through of the input TransmissionReference field. |
TransmissionResults |
Lists error codes from any errors caused by the most recent request as a whole. |
Version |
Total number of records. |
Record Level Response Fields#
Output Name |
Description |
---|---|
AddressKey |
A unique identifier for an address. This key can be used with other current and future Melissa Data services. |
AddressLine1 |
The street address. |
City |
The city of the output address. |
Distance |
The distance in miles between the input coordinates and the output coordinates. |
Latitude |
The latitude geographic coordinate of the output address. |
Longitude |
The longitude geographic coordinate of the output address. |
MelissaAddressKey |
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. |
MelissaAddressKeyBase |
The Melissa Address Key Base (BaseMAK). Every full address has its own Melissa Address Key (MAK). If that address is a suite or apartment, we will also return a Melissa Address Key Base (BaseMAK) that corresponds to the overall building. |
PostalCode |
The postal code of the output address. |
RecordID |
The number of the record. Always 1 for a single request, otherwise it serves as an index of the array of records. |
Results |
Comma delimited status, error codes, and change codes for the record. |
State |
The state of the output address. |
SuiteCount |
The number of suites in a particular building. |
SuiteName |
The suite name of the address returned. |
/V3/WEB/ReverseGeoCode/doLookupPostalCodes#
The Reverse GeoCoder doLookupPostalCodes endpoint will lookup addresses by choosing the actions and options needed.
Try It Now#
curl -X GET "https://reversegeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookupPostalCodes?\
&dist="10"\
&format=json\
&id={{customerId}}\
&lat="33.63756710910554"\
&long="-117.60695049134513"\
&opt=\
&recs=\
&t=Test" \
-H "Content-Type: application/json" \
-H "Accept: application/json"
curl -X POST "https://reversegeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookupPostalCodes" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"CustomerId": {{customerId}},
"Latitude": "33.63756710910554",
"Longitude": "-117.60695049134513",
"MaxDistance": "10",
"MaxRecords": "",
"Options": "",
"TransmissionReference": "Test"
}'
curl -X GET "https://reversegeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookupPostalCodes?\
&dist="10"\
&format=xml\
&id={{customerId}}\
&lat="33.63756710910554"\
&long="-117.60695049134513"\
&opt=\
&recs=\
&t=Test" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml"
curl -X POST "https://reversegeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookupPostalCodes" \
-H "Content-Type: application/xml" \
-H "Accept: application/xml" \
-d '<RequestArray>
<CustomerId>{{customerId}}</CustomerId>
<Latitude>33.63756710910554</Latitude>
<Longitude>-117.60695049134513</Longitude>
<MaxDistance>10</MaxDistance>
<MaxRecords></MaxRecords>
<Options></Options>
<TransmissionReference>Test</TransmissionReference>
</RequestArray>'
Request Parameters#
Code |
Description |
||
---|---|---|---|
Request Level Parameters |
|||
|
The requested maximum distance in miles. The maximum value is |
||
|
The License Key issued by Melissa. |
||
|
The desired format of the response. Accepts |
||
|
The latitude geographic coordinate in decimal format. |
||
|
The longitude geographic coordinate in decimal format. |
||
|
|||
|
The requested number of records. The maximum value is |
||
|
Optional. Serves as a unique request identifier. |
Code |
Description |
||
---|---|---|---|
Request Level Parameters |
|||
|
The License Key issued by Melissa. |
||
|
The latitude geographic coordinate in decimal format. |
||
|
The longitude geographic coordinate in decimal format. |
||
|
The requested maximum distance in miles. The maximum value is |
||
|
The requested number of records. The maximum value is |
||
|
|||
|
Optional. Serves as a unique request identifier. |
Code |
Description |
||
---|---|---|---|
Request Level Parameters |
|||
|
The requested maximum distance in miles. The maximum value is |
||
|
The License Key issued by Melissa. |
||
|
The desired format of the response. Accepts |
||
|
The latitude geographic coordinate in decimal format. |
||
|
The longitude geographic coordinate in decimal format. |
||
|
|||
|
The requested number of records. The maximum value is |
||
|
Optional. Serves as a unique request identifier. |
Code |
Description |
||
---|---|---|---|
Request Level Parameters |
|||
|
The License Key issued by Melissa. |
||
|
The latitude geographic coordinate in decimal format. |
||
|
The longitude geographic coordinate in decimal format. |
||
|
The requested maximum distance in miles. The maximum value is |
||
|
The requested number of records. The maximum value is |
||
|
|||
|
Optional. Serves as a unique request identifier. |
Options#
List options in the following format, with multiple options delimited with a ,
.
OptionName:Parameter,OptionName:Parameter
Level#
This option specifies the level of data to search. Depending on which parameter you set for Level, you can return the ZIP, ZIP+4, or ZIP and Carrier Route with your records.
Parameter |
Description |
||
---|---|---|---|
|
Two fields are returned for each record:
|
||
|
Two fields are returned for each record:
|
||
|
Default. A single field is returned for each record:
|
Headers#
Content-Type: application/json
Accept: application/json
Content-Type: application/json
Accept: application/json
Content-Type: application/xml
Accept: application/xml
Content-Type: application/xml
Accept: application/xml
Response#
{
"Version": "6.2.0.5179",
"TransmissionReference": "",
"TransmissionResults": "",
"Results": "GS07",
"TotalRecords": 1,
"Records":
[{
"City": "RANCHO SANTA MARGARITA",
"State": "CA",
"PostalCode": "92688",
"Latitude": "33.6369",
"Longitude": "-117.6043",
"Distance": "0.159563"
}]
}
{
"Version": "6.2.0.5179",
"TransmissionReference": "",
"TransmissionResults": "",
"Results": "GS07",
"TotalRecords": 1,
"Records":
[{
"City": "RANCHO SANTA MARGARITA",
"State": "CA",
"PostalCode": "92688",
"Latitude": "33.6369",
"Longitude": "-117.6043",
"Distance": "0.159563"
}]
}
<PostalResponseArray
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="urn:mdReverseGeoCode">
<Version>6.2.0.5179</Version>
<TransmissionReference />
<TransmissionResults />
<Results>GS07</Results>
<TotalRecords>1</TotalRecords>
<Records>
<PostalLookupResponseRecord>
<City>RANCHO SANTA MARGARITA</City>
<State>CA</State>
<PostalCode>92688</PostalCode>
<Latitude>33.6369</Latitude>
<Longitude>-117.6043</Longitude>
<Distance>0.159563</Distance>
</PostalLookupResponseRecord>
</Records>
</PostalResponseArray>
<PostalResponseArray
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns="urn:mdReverseGeoCode">
<Version>6.2.0.5179</Version>
<TransmissionReference />
<TransmissionResults />
<Results>GS07</Results>
<TotalRecords>1</TotalRecords>
<Records>
<PostalLookupResponseRecord>
<City>RANCHO SANTA MARGARITA</City>
<State>CA</State>
<PostalCode>92688</PostalCode>
<Latitude>33.6369</Latitude>
<Longitude>-117.6043</Longitude>
<Distance>0.159563</Distance>
</PostalLookupResponseRecord>
</Records>
</PostalResponseArray>
Service Level Response Fields#
Output Name |
Description |
---|---|
TotalRecords |
The current service version number. |
TransmissionReference |
A pass-through of the input TransmissionReference field. |
TransmissionResults |
Lists error codes from any errors caused by the most recent request as a whole. |
Version |
Total number of records. |
Record Level Response Fields#
Output Name |
Description |
---|---|
City |
The city of the output address. |
State |
The state of the output address. |
PostalCode |
The postal code of the output address. |
Carrier Route |
Returns the 5-digit Postal Code of the output address. If the Level option is set to Plus4 this field will instead return the 9-digit ZIP+4 of the output address. |
Latitude |
The latitude geographic coordinate of the output address. |
Longitude |
The longitude geographic coordinate of the output address. |
Distance |
The distance in miles between the input coordinates and the output coordinates. |
/V3/WEB/ReverseGeoCode/doLookupFromList#
Reverse GeoCoder can take in an origin address and one or more target addresse(s) to perform a distance comparison and return the closest target addresse(s) to the origin address.
Try It Now#
curl -X POST "https://ReverseGeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookupFromList" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"CustomerId": {{customerId}},
"Latitude": "33.63756710910554",
"Longitude": "-117.60695049134513",
"MaxDistance": "10",
"MaxRecords": "",
"Options": "",
"Records":
[{
"MelissaAddressKey": "8008006245",
"RecordID": "1"
},{
"MelissaAddressKey": "5328287925",
"RecordID": "2"
}],
"TransmissionReference": "Reverse Geo LookupFromList Test"
}'
Request Parameters#
Code |
Description |
||||
---|---|---|---|---|---|
Request Level Parameters |
|||||
|
The License Key issued by Melissa. |
||||
|
The latitude geographic coordinate in decimal format. |
||||
|
The longitude geographic coordinate in decimal format. |
||||
|
The requested maximum distance in miles. The maximum value is |
||||
|
The Melissa Address Key (MAK) for the origin address lookup. The set distance will be calculated from here to the possible target addresses. |
||||
|
The requested number of records. The maximum value is |
||||
|
|||||
|
Optional. Serves as a unique request identifier. |
||||
Record Level Parameters |
|||||
|
The Melissa Address Key (MAK) for a possible target address. You send in possible target addresses to lookup against the the origin address. You can send in more possible target addresses than your set |
||||
|
This is a string value containing a unique identifier for the current record. Use this to match the record submitted with the record returned. It will return what is inputted. |
Options#
List options in the following format, with multiple options delimited with a ,
.
OptionName:Parameter,OptionName:Parameter
IncludeApartments#
This options allows you to include records with a non-null baseMAK.
Default of Off
will not include non-null basekMAK records.
Parameter |
Description |
---|---|
|
Include apartments. |
|
Default. Do not include apartments. |
IncludeEmptyLots#
This options allows you to specify if you want to include addresses that are empty lots in your search.
Parameter |
Description |
---|---|
|
Include empty lots. |
|
Default. Do not include empty lots. |
IncludeUndeliverable#
This options allows you to specify if you want to include addresses we have identified as unable to deliver mail to.
Default of Off
will not include undeliverable addresses.
Parameter |
Description |
---|---|
|
Default. Include undeliverable addresses. |
|
Do not include undeliverable addresses. |
Headers#
Content-Type: application/json
Accept: application/json
Response#
{
"Version": "6.2.0.5179",
"TransmissionReference": "Test",
"TransmissionResults": "",
"Results": "GS07",
"TotalRecords": 1,
"Records":
[{
"AddressLine1": "22382 Avenida Empresa",
"SuiteName": "",
"SuiteCount": "0",
"City": "Rancho Santa Margarita",
"State": "CA",
"PostalCode": "92688",
"AddressKey": "92688211282",
"Latitude": "33.637562",
"Longitude": "-117.606887",
"Distance": "0.003677",
"MelissaAddressKey": "8008006245",
"MelissaAddressKeyBase": "0",
"RecordID": "1"
}]
}
Service Level Response Fields#
Output Name |
Description |
---|---|
TotalRecords |
The current service version number. |
TransmissionReference |
A pass-through of the input TransmissionReference field. |
TransmissionResults |
Lists error codes from any errors caused by the most recent request as a whole. |
Version |
Total number of records. |
Record Level Response Fields#
Output Name |
Description |
---|---|
RecordID |
The number of the record. Always 1 for a single request, otherwise it serves as an index of the array of records. |
Results |
Comma delimited status, error codes, and change codes for the record. |
AddressLine1 |
The street address. |
SuiteName |
The suite name of the address returned. |
SuiteCount |
The number of suites in a particular building. |
City |
The city of the output address. |
State |
The state of the output address. |
PostalCode |
The postal code of the output address. |
AddressKey |
A unique identifier for an address. This key can be used with other current and future Melissa Data services. |
Latitude |
The latitude geographic coordinate of the output address. |
Longitude |
The longitude geographic coordinate of the output address. |
Distance |
The distance in miles between the input coordinates and the output coordinates. |
MelissaAddressKey |
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. |
MelissaAddressKeyBase |
The Melissa Address Key Base (BaseMAK). Every full address has its own Melissa Address Key (MAK). If that address is a suite or apartment, we will also return a Melissa Address Key Base (BaseMAK) that corresponds to the overall building. |
Result Codes#
For details of all result codes please visit here
Result codes yield more granular information about a given address.
They are returned as a comma-delimited string of 4-character alpha-numeric codes, e.g. GS07
.
GS## and GE## Codes#
The GS## and GE## codes (Geocode Status and Geocode Error) are returned alongside each address record in a request.
SE## and GE## Codes#
The SE## and GE## codes (Transmission Service Error and General Transmission Error) are used to signify more general errors, and are returned under the key TransmissionResults
in the outermost level of our responses.
Service Level Result Codes#
Code |
Short Description |
Long Description |
---|---|---|
Transmission Service Error |
||
|
Cloud Service Internal Error |
The cloud service experienced an internal error. |
General Transmission Error |
||
|
Empty Request Structure |
The SOAP, JSON, or XML request structure is empty. Not to be confused with the GE01 GeoCode result code. |
|
Empty License Key |
The License Key is empty. |
|
Invalid License Key |
The License Key is invalid. |
|
Disabled License Key |
The License Key is disabled. |
|
Invalid Request |
The SOAP, JSON, or XML request is invalid. |
|
Customer Does Not Exist |
The Customer ID is not in our system. |
|
Customer License Disabled |
The encrypted license is on the ban list. |
|
Customer Disabled |
The Customer ID is disabled. |
|
IP Blacklisted |
The IP Address is on the global ban list. |
|
IP Not Whitelisted |
The IP Address is not on the customer’s whitelist. |
Record Level Result Codes#
Code |
Short Description |
Long Description |
---|---|---|
GS - Geocode Status |
||
|
Records Found |
The service successfully reverse geocoded the input coordinates and returned addresses. |
GE - Geocode Error |
||
|
Job ID Not Found |
The job ID was not found. |
|
Job Not Ready |
The job is not ready. |
|
No Record in Job |
There was no record found in the job. |
|
Record Total Mismatch |
The received record total does not match the user-specified RecordCount. |
|
Job in Queue |
The job is in the queue. |