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#
Introduction#
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?\
id={{customerId}}\
&lat="33.63756710910554"\
&long="-117.60695049134513"\
&dist="100"\
&recs=\
&t=\
&opt=\
&format=JSON" \
-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":"100",
"MaxRecords":"",
"Options":"",
"TransmissionReference":"ReverseGeo DoLookup Test"
}'
curl -X GET "https://ReverseGeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookup?\
id={{customerId}}\
&lat="33.63756710910554"\
&long="-117.60695049134513"\
&dist="100"\
&recs=\
&t=\
&opt=\
&format=XML" \
-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>100</MaxDistance>
<MaxRecords></MaxRecords>
<Options></Options>
<TransmissionReference>ReverseGeo DoLookup Test</TransmissionReference>
</RequestArray>'
Request Parameters#
Code |
Description |
|||
---|---|---|---|---|
t |
This is a string value that serves as a unique identifier for this set of records. It is returned as sent. |
|||
id |
The License Key issued by Melissa. |
|||
lat |
The latitude geographic coordinate in decimal format. |
|||
long |
The longitude geographic coordinate in decimal format. |
|||
dist |
The requested maximum distance in miles. |
|||
recs |
The requested number of records. |
|||
opt |
|
|||
format |
The desired format of the response. |
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 |
---|---|
Version |
The current service version number. |
TransmissionReference |
Optional. Serves as a unique request identifier. |
TransmissionResults |
Lists error codes from any errors caused by the most recent request as a whole. |
TotalRecords |
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. |
Options#
List options in the following format, with multiple options delimited with a ,
.
OptionName:Parameter,OptionName:Parameter
Include Apartments#
This options allows you to include records with a non-null baseMAK. Default of “off” will not include non-null basekMAK records.
Parameter |
Description |
---|---|
On |
Include apartments. |
Off |
Do not include apartments. |
Include Undeliverable#
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 |
---|---|
On |
Include undeliverable addresses. |
Off |
Do not include undeliverable addresses. |
Include Empty Lots#
Parameter |
Description |
---|---|
On |
Include empty lots. |
Off |
Do not include empty lots. |
/V3/WEB/ReverseGeoCode/doLookupPostalCodes#
Introduction#
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\
?id={{customerId}}\
&lat="33.63756710910554"\
&long="-117.60695049134513"\
&dist="100"\
&recs=\
&t=\
&opt=\
&format=json" \
-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":"100",
"MaxRecords":"",
"Options":"",
"TransmissionReference":"ReverseGeo DoLookup Test"
}'
curl -X GET "https://reversegeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookupPostalCodes\
?id={{customerId}}\
&lat="33.63756710910554"\
&long="-117.60695049134513"\
&dist=\
&recs=\
&t=\
&opt=\
&format=xml" \
-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>100</MaxDistance>
<MaxRecords></MaxRecords>
<Options></Options>
<TransmissionReference>ReverseGeo DoLookup Test</TransmissionReference>
</RequestArray>'
Request Parameters#
Code |
Description |
|
---|---|---|
t |
This is a string value that serves as a unique identifier for this set of records. It is returned as sent. |
|
id |
The License Key issued by Melissa. |
|
lat |
The latitude geographic coordinate in decimal format. |
|
long |
The longitude geographic coordinate in decimal format. |
|
dist |
The requested maximum distance in miles. |
|
recs |
The requested number of records. |
|
opt |
|
|
format |
The desired format of the response. |
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 |
---|---|
Version |
The current service version number. |
TransmissionReference |
Optional. Serves as a unique request identifier. |
TransmissionResults |
Lists error codes from any errors caused by the most recent request as a whole. |
TotalRecords |
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. |
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.
First header |
Second header |
---|---|
PostalCode |
|
CarrierRoute |
|
Plus4 |
|
/V3/WEB/ReverseGeoCode/doLookupFromList#
Introduction#
The Reverse GeoCoder doLookupFormList endpoint will lookup input addresses if they are within the parameters and options specified.
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": "100",
"MaxRecords": "",
"Options": "",
"TransmissionReference": "Reverse Geo LookupFromList Test",
"Records": [
{
"RecordID": "1",
"MelissaAddressKey": "8008006245"
},
{
"RecordID": "2",
"MelissaAddressKey": "5328287925"
}
]
}'
Request Parameters#
Code |
Description |
|||
---|---|---|---|---|
t |
This is a string value that serves as a unique identifier for this set of records. It is returned as sent. |
|||
id |
The License Key issued by Melissa. |
|||
lat |
The latitude geographic coordinate in decimal format. |
|||
long |
The longitude geographic coordinate in decimal format. |
|||
dist |
The requested maximum distance in miles. |
|||
recs |
The requested number of records. |
|||
opt |
|
|||
format |
The desired format of the response. |
Headers#
Content-Type: application/json
Accept: application/json
Response#
{
"Version": "6.2.0.5179",
"TransmissionReference": "Reverse Geo LookupFromList 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 |
---|---|
Version |
The current service version number. |
TransmissionReference |
Optional. Serves as a unique request identifier. |
TransmissionResults |
Lists error codes from any errors caused by the most recent request as a whole. |
TotalRecords |
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. |
Options#
List options in the following format, with multiple options delimited with a ,
.
OptionName:Parameter,OptionName:Parameter
Include Apartments#
This options allows you to include records with a non-null baseMAK. Default of “off” will not include non-null basekMAK records.
Parameter |
Description |
---|---|
On |
Include apartments. |
Off |
Do not include apartments. |
Include Undeliverable#
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 |
---|---|
On |
Include undeliverable addresses. |
Off |
Do not include undeliverable addresses. |
Include Empty Lots#
Parameter |
Description |
---|---|
On |
Include empty lots. |
Off |
Do not include empty lots. |
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. |