Difference between revisions of "Reverse GeoCoder:doLookupFromList"

From Melissa Data Wiki
Jump to navigation Jump to search
(Created page with "{{ReverseGeoCoderNav |InputOutputCollapse= }} {{CustomTOC}} =Request= A request consists of a protocol to make a call to the service, detailing desired elements. The minimum...")
 
Line 5: Line 5:


{{CustomTOC}}
{{CustomTOC}}
The doLooupFromList endpoint takes in a '''target''' address (lookup) and one or more '''satellite''' addresses (list) to perform a distance comparison and return the closest satellite addresses to the target address.
=Request=
=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.
A request consists of a protocol to make a call to the service, detailing desired elements.


==URL==
==URL==
Line 27: Line 29:
!Field Name !! Level !! JSON
!Field Name !! Level !! JSON
|-
|-
|Transmission Reference||rowspan="11" valign="center"|Request||TransmissionReference
|[[#Transmission Reference|Transmission Reference]]||rowspan="11" valign="center"|Request||TransmissionReference
|-
|-
|License Key||CustomerID
|[[#License Key|License Key]]||CustomerID
|-
|-
|Latitude||Latitude
|[[#Latitude|Latitude]]||Latitude
|-
|-
|Longitude||Longitude
|[[#Longitude|Longitude]]||Longitude
|-
|-
|Melissa Address Key||MelissaAddressKey
|[[#Melissa Address Key (Target)|Melissa Address Key (Target)]]||MelissaAddressKey
|-
|-
|MaxDistance||MaxDistance
|[[#Max Distance|Max Distance]]||MaxDistance
|-
|-
|MaxRecords||MaxRecords
|[[#Max Records|Max Records]]||MaxRecords
|-
|-
|Options||Options
|[[#Options|Options]]||Options
|-
|-
|Records||Records
|[[#Records|Records]]||Records
|-
|-
|Record ID||RecordID
|[[#Record ID|Record ID]]||RecordID
|-
|-
|Melissa AddressKey||MelissaAddressKey
|[[#Melissa Address Key (Satellite)|Melissa Address Key (Satellite)]]||MelissaAddressKey
|}
|}


Line 82: Line 84:
:''Required.''
:''Required.''


:The latitude geographic coordinate in decimal format.
:The latitude geographic coordinate in decimal format for the target address lookup.


:{| class="alternate01"
:{| class="alternate01"
Line 94: Line 96:
:''Required.''
:''Required.''


:The longitude geographic coordinate in decimal format.
:The longitude geographic coordinate in decimal format for the target address lookup.


:{| class="alternate01"
:{| class="alternate01"
Line 103: Line 105:




<h3 class="h3grey">MaxDistance</h3>
<h3 class="h3grey">Melissa Address Key (Target)</h3>
:The Melissa Address Key (MAK) for the target address lookup. The set distance will be calculated from here to the satellite addresses.
 
:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"MelissaAddressKey":"'''''string'''''"</code>
|}
 
 
<h3 class="h3grey">Max Distance</h3>
:''Optional.''
:''Optional.''


:The requested maximum distance in miles. The maximum possible distance is 10 miles. If no MaxDistance is specified, the default is 10 miles.
:The requested maximum distance in miles from the target address to the satellite addresses. The maximum possible distance is 10 miles. If no MaxDistance is specified, the default is 10 miles.


:{| class="alternate01"
:{| class="alternate01"
Line 115: Line 127:




<h3 class="h3grey">MaxRecords</h3>
<h3 class="h3grey">Max Records</h3>
:''Optional.''
:''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.
:The maximum requested number of satellite addresses to return from the lookup. The Maximum number of records the user can get is 100 records. This is also the default if no MaxRecords is specified.
 
:It is common to have more input satellite addresses than your requested satellite address amount.


:{| class="alternate01"
:{| class="alternate01"
Line 130: Line 144:
:''Optional.''
:''Optional.''


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


:{| class="alternate01"
:{| class="alternate01"
Line 148: Line 162:




:<h4 style="border-bottom:1px solid black;">TEST</h4>
:<h4 style="border-bottom:1px solid black;">IncludeApartments</h4>
::This options is a test.
::This options allows you to include records with a non-null baseMAK.


::{| class="alternate01 sortable"
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
!Option Name !! Parameter !! Description
|-
|-
|rowspan="2"|'''TEST'''||<code>Off</code>||'''''Default.''''' Test.
|rowspan="2"|'''IncludeApartments'''||<code>Off</code>||'''''Default.''''' Non-null baseMAK records are not included.
|-
|-
|<code>On</code>||
|<code>On</code>||Records with a non-null baseMAK will be included in your search.
|}
 
 
:<h4 style="border-bottom:1px solid black;">IncludeUndeliverable</h4>
::This options allows you to specify if you want to include addresses we have identified as unable to deliver mail to.
 
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''IncludeUndeliverable'''||<code>Off</code>||Undeliverable addresses are not included.
|-
|<code>On</code>||'''''Default.''''' Undeliverable addresses are included in your search.
|}
 
 
:<h4 style="border-bottom:1px solid black;">IncludeEmptyLots</h4>
::This options allows you to specify if you want to include addresses that are empty lots in your search.
 
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="2"|'''IncludeEmptyLots'''||<code>Off</code>||'''''Default.''''' Empty lots are not included.
|-
|<code>On</code>||Empty lots are included in your search.
|}
|}




<h3 class="h3grey">Records</h3>
<h3 class="h3grey">Records</h3>
:
:This is a record array containing your input satellite addresses.


:{| class="alternate01"
:{| class="alternate01"
Line 170: Line 208:




<h3 class="h3grey">RecordID</h3>
<h3 class="h3grey">Record ID</h3>
:
:This is a unique record string identity you set.


:{| class="alternate01"
:{| class="alternate01"
Line 180: Line 218:




<h3 class="h3grey">MelissaAddressKey</h3>
<h3 class="h3grey">Melissa Address Key (Satellite)</h3>
:
:This is the Melissa Address Key (MAK)* for an input satellite address. You send in satellite addresses to lookup against the the target address.
 
:You can have more input satellite addresses than your set [[#Max Records|Max Records]].
 
:<nowiki>*</nowiki>MAK is only generated by Melissa products.


:{| class="alternate01"
:{| class="alternate01"
Line 192: Line 234:
=Response=
=Response=
A response is the result of a request. This consists of returned results codes and returned addresses, depending on the input provided.
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==
==Field Names==
Line 201: Line 241:
!Field Name !! Level !! JSON/XML
!Field Name !! Level !! JSON/XML
|-
|-
|Version||rowspan="5" valign="center"|Response (Base)||Version
|[[#Version|Version]]||rowspan="5" valign="center"|Response (Base)||Version
|-
|-
|Transmission Reference||TransmissionReference
|[[#Transmission Reference|Transmission Reference]]||TransmissionReference
|-
|-
|Transmission Results||TransmissionResults
|[[#Transmission Results|Transmission Results]]||TransmissionResults
|-
|-
|Results||Results
|[[#Results|Results]]||Results
|-
|-
|Total Records||TotalRecords
|[[#Total Records|Total Records]]||TotalRecords
|-
|-
|Records||rowspan="14" valign="center"|Record||Records
|[[#Records|Records]]||rowspan="14" valign="center"|Record||Records
|-
|-
|Address Line 1||AddressLine1
|[[#Address Line 1|Address Line 1]]||AddressLine1
|-
|-
|Suite Name||SuiteName
|[[#Suite Name|Suite Name]]||SuiteName
|-
|-
|Suite Count||SuiteCount
|[[#Suite Count|Suite Count]]||SuiteCount
|-
|-
|City||City
|[[#City|City]]||City
|-
|-
|State||State
|[[#State|State]]||State
|-
|-
|Postal Code||PostalCode
|[[#Postal Code|Postal Code]]||PostalCode
|-
|-
|AddressKey||AddressKey
|[[#AddressKey|AddressKey]]||AddressKey
|-
|-
|Latitude||Latitude
|[[#Latitude|Latitude]]||Latitude
|-
|-
|Longitude||Longitude
|[[#Longitude|Longitude]]||Longitude
|-
|-
|Distance||Distance
|[[#Distance|Distance]]||Distance
|-
|-
|Melissa AddressKey||MelissaAddressKey
|[[#Melissa Address Key|Melissa Address Key]]||MelissaAddressKey
|-
|-
|Melissa AddressKey Base||MelissaAddressKeyBase
|[[#Melissa Address Key Base|Melissa Address Key Base]]||MelissaAddressKeyBase
|-
|-
|Record ID||RecordID
|[[#Record ID|Record ID]]||RecordID
|}
|}


Line 309: Line 349:




<h3 class="h3grey">AddressLine1</h3>
<h3 class="h3grey">Address Line 1</h3>
:Returns the street address (street number and street name) that corresponds to the input geo coordinates.
:Returns the street address (street number and street name) for this satellite address.


:{| class="alternate01"
:{| class="alternate01"
Line 319: Line 359:




<h3 class="h3grey">SuiteName</h3>
<h3 class="h3grey">Suite Name</h3>
:Returns the suite name of the address returned. Values that could be returned are: Ste, Apt., etc.
:Returns the suite name of the address returned. Values that could be returned are: Ste, Apt., etc.


Line 329: Line 369:




<h3 class="h3grey">SuiteCount</h3>
<h3 class="h3grey">Suite Count</h3>
:Returns the number of suites in a particular building. Zero will be returned if the address has a no suites (a single delivery point).
:Returns the number of suites in a particular building. Zero will be returned if the address has a no suites (a single delivery point).


Line 340: Line 380:


<h3 class="h3grey">City</h3>
<h3 class="h3grey">City</h3>
:Returns the city of the output address.
:Returns the city of this satellite address.


:{| class="alternate01"
:{| class="alternate01"
Line 350: Line 390:


<h3 class="h3grey">State</h3>
<h3 class="h3grey">State</h3>
:Returns the State of the output address.
:Returns the State of this satellite address.


:{| class="alternate01"
:{| class="alternate01"
Line 359: Line 399:




<h3 class="h3grey">PostalCode</h3>
<h3 class="h3grey">Postal Code</h3>
:Returns the Postal Code of the output address.
:Returns the 5-digit Postal Code of this satellite address.


:{| class="alternate01"
:{| class="alternate01"
Line 370: Line 410:


<h3 class="h3grey">AddressKey</h3>
<h3 class="h3grey">AddressKey</h3>
:Returns the address's addresskey.
:Returns this satellite address's AddressKey (USPS).


:{| class="alternate01"
:{| class="alternate01"
Line 380: Line 420:


<h3 class="h3grey">Latitude</h3>
<h3 class="h3grey">Latitude</h3>
:Returns the latitude geographic coordinate of the output address.
:Returns the latitude geographic coordinate of this satellite address.


:{| class="alternate01"
:{| class="alternate01"
Line 390: Line 430:


<h3 class="h3grey">Longitude</h3>
<h3 class="h3grey">Longitude</h3>
:Returns the longitude geographic coordinate of the output address.
:Returns the longitude geographic coordinate of this satellite address.


:{| class="alternate01"
:{| class="alternate01"
Line 400: Line 440:


<h3 class="h3grey">Distance</h3>
<h3 class="h3grey">Distance</h3>
:Returns the distance in miles 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.
:Returns the distance in miles between the target address and this satellite address. A distance of zero indicates that an exact address match was returned for the input geographic coordinates.


:{| class="alternate01"
:{| class="alternate01"
Line 409: Line 449:




<h3 class="h3grey">MelissaAddressKey</h3>
<h3 class="h3grey">Melissa Address Key</h3>
: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.
: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.


Line 421: Line 461:




<h3 class="h3grey">MelissaAddressKeyBase</h3>
<h3 class="h3grey">Melissa Address Key Base</h3>
: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.
: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.


Line 431: Line 471:




<h3 class="h3grey">RecordID</h3>
<h3 class="h3grey">Record ID</h3>
:
:This is the same unique record string identity you set for this satellite address in the request.


:{| class="alternate01"
:{| class="alternate01"

Revision as of 16:45, 8 October 2021

← Reverse GeoCoder

Reverse GeoCoder Navigation
Introduction
Licensing
Input/Output
doLookup
  ↳  Request
  ↳  Response
doLookupPostalCodes
  ↳  Request
  ↳  Response
doLookupFromList
  ↳  Request
  ↳  Response
Examples
REST XML
REST JSON
JSON
XML
Result Codes
Result Code Use
Reverse GeoCoder Result Codes
Sample Code



The doLooupFromList endpoint takes in a target address (lookup) and one or more satellite addresses (list) to perform a distance comparison and return the closest satellite addresses to the target address.

Request

A request consists of a protocol to make a call to the service, detailing desired elements.

URL

doLookupFromList

Supports JSON
Use URL
Secure https://reversegeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookupFromList

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 JSON
Transmission Reference Request TransmissionReference
License Key CustomerID
Latitude Latitude
Longitude Longitude
Melissa Address Key (Target) MelissaAddressKey
Max Distance MaxDistance
Max Records MaxRecords
Options Options
Records Records
Record ID RecordID
Melissa Address Key (Satellite) MelissaAddressKey

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"


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"


Latitude

Required.
The latitude geographic coordinate in decimal format for the target address lookup.
Protocol Syntax
JSON "Latitude":"string"


Longitude

Required.
The longitude geographic coordinate in decimal format for the target address lookup.
Protocol Syntax
JSON "Longitude":"string"


Melissa Address Key (Target)

The Melissa Address Key (MAK) for the target address lookup. The set distance will be calculated from here to the satellite addresses.
Protocol Syntax
JSON "MelissaAddressKey":"string"


Max Distance

Optional.
The requested maximum distance in miles from the target address to the satellite addresses. The maximum possible distance is 10 miles. If no MaxDistance is specified, the default is 10 miles.
Protocol Syntax
JSON "MaxDistance":"string"


Max Records

Optional.
The maximum requested number of satellite addresses to return from the lookup. The Maximum number of records the user can get is 100 records. This is also the default if no MaxRecords is specified.
It is common to have more input satellite addresses than your requested satellite address amount.
Protocol Syntax
JSON "MaxRecords":"string"


Options

Optional.
This is a string value containing the options you set.
Protocol Syntax
JSON "Options":"string"


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.


Records

This is a record array containing your input satellite addresses.
Protocol Syntax
JSON "Records":"string"


Record ID

This is a unique record string identity you set.
Protocol Syntax
JSON "RecordID":"string"


Melissa Address Key (Satellite)

This is the Melissa Address Key (MAK)* for an input satellite address. You send in satellite addresses to lookup against the the target address.
You can have more input satellite addresses than your set Max Records.
*MAK is only generated by Melissa products.
Protocol Syntax
JSON "MelissaAddressKey":"string"


Response

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

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
Melissa Address Key MelissaAddressKey
Melissa Address Key Base MelissaAddressKeyBase
Record ID RecordID

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"


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"


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"


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"


Total Records

Displays the total number of records returned.
Protocol Syntax
JSON "TotalRecords":"string"


Response Record Elements

JSON will only contain the Records element.

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

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


Address Line 1

Returns the street address (street number and street name) for this satellite address.
Protocol Syntax
JSON "AddressLine1":"string"


Suite Name

Returns the suite name of the address returned. Values that could be returned are: Ste, Apt., etc.
Protocol Syntax
JSON "SuiteName":"string"


Suite Count

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"


City

Returns the city of this satellite address.
Protocol Syntax
JSON "City":"string"


State

Returns the State of this satellite address.
Protocol Syntax
JSON "State":"string"


Postal Code

Returns the 5-digit Postal Code of this satellite address.
Protocol Syntax
JSON "PostalCode":"string"


AddressKey

Returns this satellite address's AddressKey (USPS).
Protocol Syntax
JSON "AddressKey":"string"


Latitude

Returns the latitude geographic coordinate of this satellite address.
Protocol Syntax
JSON "Latitude":"string"


Longitude

Returns the longitude geographic coordinate of this satellite address.
Protocol Syntax
JSON "Longitude":"string"


Distance

Returns the distance in miles between the target address and this satellite address. A distance of zero indicates that an exact address match was returned for the input geographic coordinates.
Protocol Syntax
JSON "Distance":"string"


Melissa Address Key

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"


Melissa Address Key Base

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"


Record ID

This is the same unique record string identity you set for this satellite address in the request.
Protocol Syntax
JSON "RecordID":"string"
Retrieved from "http://wiki.melissadata.com/index.php?title=Reverse_GeoCoder:doLookupFromList&oldid=18177"