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#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML
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

Set Options

IncludeApartments

IncludeUndeliverable

IncludeEmptyLots

format

The desired format of the response.

Headers#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML
 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#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML
 {
    "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#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML
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

Set Options

Level

format

The desired format of the response.

Headers#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML
 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#

  • GET JSON
  • POST JSON
  • GET XML
  • POST XML
  {
    "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
Default. A single field is returned for each record:

  • PostalCode: A 5-digit postal code.

CarrierRoute
Two fields are returned for each record:

  • PostalCode: A 5-digit postal code.

  • CarrierRoute: the nearest Carrier Route.

Plus4
Two fields are returned for each record:

  • PostalCode: a 9-digit ZIP+4 Postal Code

  • CarrierRoute: the nearest Carrier Route.

/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#

  • POST JSON
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

Set Options

IncludeApartments

IncludeUndeliverable

IncludeEmptyLots

format

The desired format of the response.

Headers#

  • POST JSON
 Content-Type: application/json
 Accept: application/json

Response#

  • POST JSON
 {
    "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

SE01

Cloud Service Internal Error

The cloud service experienced an internal error.

General Transmission Error

GE01

Empty Request Structure

The SOAP, JSON, or XML request structure is empty. Not to be confused with the GE01 GeoCode result code.

GE04

Empty License Key

The License Key is empty.

GE05

Invalid License Key

The License Key is invalid.

GE06

Disabled License Key

The License Key is disabled.

GE07

Invalid Request

The SOAP, JSON, or XML request is invalid.

GE09

Customer Does Not Exist

The Customer ID is not in our system.

GE10

Customer License Disabled

The encrypted license is on the ban list.

GE11

Customer Disabled

The Customer ID is disabled.

GE12

IP Blacklisted

The IP Address is on the global ban list.

GE13

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

GS07

Records Found

The service successfully reverse geocoded the input coordinates and returned addresses.

GE - Geocode Error

GE50

Job ID Not Found

The job ID was not found.

GE51

Job Not Ready

The job is not ready.

GE52

No Record in Job

There was no record found in the job.

GE53

Record Total Mismatch

The received record total does not match the user-specified RecordCount.

GE54

Job in Queue

The job is in the queue.