Skip to content
/Lookup Postal Codes

Reverse GeoCoder

Overview

The Reverse GeoCoder Cloud API 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.

Reverse GeoCoder can be used to:

  • 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.

Documentation

Useful Resources

Product Page

https://www.melissa.com/geocoding

Support Center

https://www.melissa.com/company/product-support

Download OpenAPI description
reverse-geocoder.json
reverse-geocoder.yaml
Languages
Servers
Reverse GeoCoder Server
https://reversegeo.melissadata.net/v3/web/ReverseGeoCode/

Lookup Addresses

Use this endpoint to lookup addresses closest to the input coordinates.

Operations

Lookup Postal Codes

Use this endpoint to lookup postal codes closest to the input coordinates.

Operations

Lookup a postal code from geo location

Request

Uses HTTP GET to accept one input record and returns the response in JSON or XML format.

Query
tstring

Transmission Reference - Serves as a unique identifier for this set of records.

Example: t=Test
idany(password)required

The License Key issued by Melissa.

Example: id={REPLACE-WITH-YOUR-LICENSE-KEY}
latstringrequired

Latitude in decimal format.

Example: lat=33.63756710910554
longstringrequired

Longitude in decimal format.

Example: long=-117.60695049134513
distnumber<= 10

Maximum Distance - The requested maximum distance in miles.

Default 10
Example: dist=10
recsnumber<= 100

Maximum Records - The requested number of records.

Default 100
optstring

Options - Specify which options to use for the selected action. List of options in <OptionName>:<Parameter> format. Multiple options are delimited with a ,.

For example: OptionName:Parameter,OptionName:Parameter.

  • Level:< CarrierRoute | Plus4 | PostalCode > - 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.
    • 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.
    • PostalCode - Default. Returns the nearest 5-digit Postal Code.
Enum"Level:CarrierRoute""Level:Plus4""Level:PostalCode"
formatstring

Format of the request.

Enum"json""xml"
Example: format=json
curl -i -X GET \
  'https://reversegeo.melissadata.net/v3/web/ReverseGeoCode/doLookupPostalCodes?id={REPLACE-WITH-YOUR-LICENSE-KEY}&lat=33.63756710910554&long=-117.60695049134513'

Responses

Successful response

Body
Versionstring

The current service version number.

TransmissionReferencestring

A pass-through of the input TransmissionReference field.

TransmissionResultsstring

Lists error codes from any errors caused by the most recent request as a whole. For more information, see Reverse GeoCoder Result Codes.

Resultsstring

Comma delimited status, error codes, and change codes for the record. For more information, see Reverse GeoCoder Result Codes.

TotalRecordsinteger

Total number of records.

RecordsArray of objects(PostalCodeRecord)[ 1 .. 100 ] items
Response
{
  "Version": "6.2.0.5179",
  "TransmissionReference": "",
  "TransmissionResults": "",
  "Results": "GS07",
  "TotalRecords": 1,
  "Records": [
    { … }
  ]
}

Lookup postal codes from geo location

Request

An HTTP POST is issued with the "ContentType" header specifying the format of the request and the "Accept" header specifying the format of the response.

Body
required
CustomerIdstringrequired

The License Key issued by Melissa.

Latitudestringrequired

The latitude geographic coordinate in decimal format.

Longitudestringrequired

The longitude geographic coordinate in decimal format.

MaxDistancestring

The requested maximum distance in miles. The maximum value is 10. Default is 10.

MaxRecordsstring

The requested number of records. The maximum value is 100. Default is 100.

Optionsstring

Options - Specify which options to use for the selected action. List of options in <OptionName>:<Parameter> format. Multiple options are delimited with a ,.

For example: OptionName:Parameter,OptionName:Parameter.

  • Level:< CarrierRoute | Plus4 | PostalCode > - 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.
    • 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.
    • PostalCode - Default. Returns the nearest 5-digit Postal Code.
TransmissionReferencestring

Optional. Serves as a unique request identifier.

curl -i -X POST \
  https://reversegeo.melissadata.net/v3/web/ReverseGeoCode/doLookupPostalCodes \
  -H 'Content-Type: application/json' \
  -d '{
    "CustomerId": "{REPLACE-WITH-YOUR-LICENSE-KEY}",
    "Latitude": "33.63756710910554",
    "Longitude": "-117.60695049134513",
    "MaxDistance": "10",
    "MaxRecords": "",
    "Options": "",
    "TransmissionReference": "Test"
  }'

Responses

Successful response

Body
Versionstring

The current service version number.

TransmissionReferencestring

A pass-through of the input TransmissionReference field.

TransmissionResultsstring

Lists error codes from any errors caused by the most recent request as a whole. For more information, see Reverse GeoCoder Result Codes.

Resultsstring

Comma delimited status, error codes, and change codes for the record. For more information, see Reverse GeoCoder Result Codes.

TotalRecordsinteger

Total number of records.

RecordsArray of objects(PostalCodeRecord)[ 1 .. 100 ] items
Response
{
  "Version": "6.2.0.5179",
  "TransmissionReference": "",
  "TransmissionResults": "",
  "Results": "GS07",
  "TotalRecords": 1,
  "Records": [
    { … }
  ]
}

Lookup From List

Use this endpoint to take in an origin address and one or more target address(es) to perform a distance comparison and return the closest target address(es) to the origin address.

Operations