Reverse GeoCoder:doLookupPostalCodes: Difference between revisions

From Melissa Data Wiki
Jump to navigation Jump to search
← Older edit
m Admin moved page Reverse GeoCoder:doLookupPostalCodes? to Reverse GeoCoder:doLookupPostalCodes without leaving a redirect: Name Fix
No edit summary
 
(3 intermediate revisions by the same user not shown)
Line 5: Line 5:


{{CustomTOC}}
{{CustomTOC}}
The doLookupPostalCodes endpoint returns Postal Codes within a specified radius.
The doLookupPostalCodes endpoint returns the nearest Postal Codes centroids within a specified radius.
 
=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. The minimum required elements in a request are your License Key and at least one set of geo-coordinates.
Line 12: Line 13:


==URL==
==URL==
{{URL-ReverseGeoCoder-doLookupPostalCodes?}}
{{URL-ReverseGeoCoder-doLookupPostalCodes}}
==Header==
==Header==
HTTP headers need to match the protocols and formats being used.
HTTP headers need to match the protocols and formats being used.
Line 30: Line 31:
!Field Name !! Level !! REST !! JSON
!Field Name !! Level !! REST !! JSON
|-
|-
|Transmission Reference||rowspan="8" valign="center"|Request||t||TransmissionReference
|[[#Transmission Reference|Transmission Reference]]||rowspan="8" valign="center"|Request||t||TransmissionReference
|-
|-
|License Key||id||CustomerID
|[[#License Key|License Key]]||id||CustomerID
|-
|-
|Latitude||lat||Latitude
|[[#Latitude|Latitude]]||lat||Latitude
|-
|-
|Longitude||long||Longitude
|[[#Longitude|Longitude]]||long||Longitude
|-
|-
|MaxDistance||dist||MaxDistance
|[[#MaxDistance|MaxDistance]]||dist||MaxDistance
|-
|-
|MaxRecords||recs||MaxRecords
|[[#MaxRecords|MaxRecords]]||recs||MaxRecords
|-
|-
|Options||opt||Options
|[[#Options|Options]]||opt||Options
|-
|-
|Format||format||  
|[[#Format|Format]]||format||  
|}
|}


Line 174: Line 175:


:<h4 style="border-bottom:1px solid black;">Level</h4>
:<h4 style="border-bottom:1px solid black;">Level</h4>
::This option specifies the level of data to search.
::This option specifies the level of data to search. Depending on which parameter you set for <code>Level</code>, you can return the ZIP, ZIP+4, or ZIP and Carrier Route with your records.


::{| class="alternate01 sortable"
::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
!Option Name !! Parameter !! Description
|-
|-
|rowspan="3"|'''Level'''||<code>PostalCode</code>||'''''Default.'''''
|rowspan="3"|'''Level'''||<code>PostalCode</code>||'''''Default.''''' A single field is returned for each record:
*[[#Postal Code|PostalCode]]: A 5-digit postal code.
|-
|-
|<code>CarrierRoute</code>||
|<code>CarrierRoute</code>||Two fields are returned for each record:
*[[#Postal Code|PostalCode]]: a 5-digit Postal Code
*[[#Carrier Route|CarrierRoute]]: the nearest Carrier Route.
|-
|-
|<code>Plus4</code>||
|<code>Plus4</code>||Two fields are returned for each record:
*[[#Postal Code|PostalCode]]: a 9-digit ZIP+4 Postal Code
*[[#Carrier Route|CarrierRoute]]: the nearest Carrier Route.
|}
|}


Line 212: Line 218:
|Version||rowspan="5" valign="center"|Response (Base)||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="8" valign="center"|Record||Records
|[[#Records|Records]]||rowspan="8" valign="center"|Record||Records
|-
|-
|City||City
|[[#City|City]]||City
|-
|-
|State||State
|[[#State|State]]||State
|-
|-
|Postal Code||PostalCode
|[[#Postal Code|Postal Code]]||PostalCode
|-
|-
|Carrier Route||CarrierRoute
|[[#Carrier Route|Carrier Route]]||CarrierRoute
|-
|-
|Latitude||Latitude
|[[#Latitude|Latitude]]||Latitude
|-
|-
|Longitude||Longitude
|[[#Longitude|Longitude]]||Longitude
|-
|-
|Distance||Distance
|[[#Distance|Distance]]||Distance
|}
|}


Line 342: Line 348:




<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 the output address.
 
:If the [[#Level|Level]] option is set to <code>Plus4</code> this field will instead return the 9-digit ZIP+4 of the output address.


:{| class="alternate01"
:{| class="alternate01"
Line 354: Line 362:




<h3 class="h3grey">CarrierRoute</h3>
<h3 class="h3grey">Carrier Route</h3>
:Returns the carrier route for an address if the <code>Level</code> option is set to <code>CarrierRoute</code>.
:This field is only returned if the [[#Level|Level]] option is set to <code>CarrierRoute</code>.
 
:This is the nearest carrier route for an address.


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

Latest revision as of 17:11, 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 doLookupPostalCodes endpoint returns the nearest Postal Codes centroids within a specified radius.

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.

Reverse GeoCoder supports multiple protocols to access the service, including JSON, REST and XML.

URL

doLookupPostalCodes

Supports REST, XML and JSON
Use URL
Secure https://reversegeo.melissadata.net/V3/WEB/ReverseGeoCode/doLookupPostalCodes

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 REST JSON
Transmission Reference Request t TransmissionReference
License Key id CustomerID
Latitude lat Latitude
Longitude long Longitude
MaxDistance dist MaxDistance
MaxRecords recs MaxRecords
Options opt Options
Format format

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"
REST ?t = string
XML <TransmissionReference>string</TransmissionReference>


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"
REST &id = string
XML <CustomerID>string</CustomerID>


Latitude

Required.
The latitude geographic coordinate in decimal format.
Protocol Syntax
JSON "Latitude":"string"
REST &lat = string
XML <Latitude>string</Latitude>


Longitude

Required.
The longitude geographic coordinate in decimal format.
Protocol Syntax
JSON "Longitude":"string"
REST &long = string
XML <Longitude>string</Longitude>


MaxDistance

Optional.
The requested maximum distance (in miles). The maximum possible distance is 10 miles. If no MaxDistance is specified, the default is 10 miles.
Protocol Syntax
JSON "MaxDistance":"string"
REST &dist = string
XML <MaxDistance>string</MaxDistance>


MaxRecords

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.
Protocol Syntax
JSON "MaxRecords":"string"
REST &recs = string
XML <MaxRecords>string</MaxRecords>


Options

Optional.
This is a string value containing the options set by the user.
Protocol Syntax
JSON "Options":"string"
REST ?opt = string
XML <Options>string</Options>


List options in the following format, with multiple options delimited with a ";".
Syntax
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.
Option Name Parameter Description
Level PostalCode Default. A single field is returned for each record:
CarrierRoute Two fields are returned for each record:
Plus4 Two fields are returned for each record:


Format

Optional.
The desired format of the response. Possible values for this option are "json" or "xml". The default value is "xml".
Protocol Syntax
REST &format = string


Response

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

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
City City
State State
Postal Code PostalCode
Carrier Route CarrierRoute
Latitude Latitude
Longitude Longitude
Distance Distance

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"
XML <Version>string</Version>


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"
XML <TransmissionReference>string</TransmissionReference>


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"
XML <TransmissionResults>string</TransmissionResults>


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"
XML <Results>string</Results>


Total Records

Displays the total number of records returned.
Protocol Syntax
JSON "TotalRecords":"string"
XML <TotalRecords>string</TotalRecords>


Response Record Elements

JSON will only contain the Records element.

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

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


City

Returns the city of the output address.
Protocol Syntax
JSON "City":"string"
XML <City>string</City>


State

Returns the State of the output address.
Protocol Syntax
JSON "State":"string"
XML <State>string</State>


Postal Code

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.
Protocol Syntax
JSON "PostalCode":"string"
XML <PostalCode>string</PostalCode>


Carrier Route

This field is only returned if the Level option is set to CarrierRoute.
This is the nearest carrier route for an address.
Protocol Syntax
JSON "CarrierRoute":"string"
XML <CarrierRoute>string</CarrierRoute>


Latitude

Returns the latitude geographic coordinate of the output address.
Protocol Syntax
JSON "Latitude":"string"
XML <Latitude>string</Latitude>


Longitude

Returns the longitude geographic coordinate of the output address.
Protocol Syntax
JSON "Longitude":"string"
XML <Longitude>string</Longitude>


Distance

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.
Protocol Syntax
JSON "Distance":"string"
XML <Distance>string</Distance>
Retrieved from "http://wiki.melissadata.com/index.php?title=Reverse_GeoCoder:doLookupPostalCodes&oldid=18179"