Reverse GeoCoder:doLookupPostalCodes - Revision history

Admin at 17:11, 8 October 2021

2021-10-08T17:11:09Z

← Older revision		Revision as of 17:11, 8 October 2021
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.

Admin at 23:59, 7 October 2021

2021-10-07T23:59:32Z

← Older revision		Revision as of 23:59, 7 October 2021
Line 180:		Line 180:
	\|-		\|-
	\|rowspan="3"\|'''Level'''\|\|<code>PostalCode</code>\|\|'''''Default.''''' A single field is returned for each record:		\|rowspan="3"\|'''Level'''\|\|<code>PostalCode</code>\|\|'''''Default.''''' A single field is returned for each record:
	*[[#~~PostalCode~~\|PostalCode]]: A 5-digit postal code.		*[[#Postal Code\|PostalCode]]: A 5-digit postal code.
	\|-		\|-
	\|<code>CarrierRoute</code>\|\|Two fields are returned for each record:		\|<code>CarrierRoute</code>\|\|Two fields are returned for each record:
	*[[#~~PostalCode~~\|PostalCode]]: a 5-digit Postal Code		*[[#Postal Code\|PostalCode]]: a 5-digit Postal Code
	*[[#~~CarrierRoute~~\|CarrierRoute]]: the nearest Carrier Route.		*[[#Carrier Route\|CarrierRoute]]: the nearest Carrier Route.
	\|-		\|-
	\|<code>Plus4</code>\|\|Two fields are returned for each record:		\|<code>Plus4</code>\|\|Two fields are returned for each record:
	*[[#~~PostalCode~~\|PostalCode]]: a 9-digit ZIP+4 Postal Code		*[[#Postal Code\|PostalCode]]: a 9-digit ZIP+4 Postal Code
	*[[#~~CarrierRoute~~\|CarrierRoute]]: the nearest Carrier Route.		*[[#Carrier Route\|CarrierRoute]]: the nearest Carrier Route.
	\|}		\|}

Admin at 23:58, 7 October 2021

2021-10-07T23:58:37Z

← Older revision		Revision as of 23:58, 7 October 2021
Line 347:		Line 347:


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

Line 361:		Line 361:


	<h3 class="h3grey">~~CarrierRoute~~</h3>		<h3 class="h3grey">Carrier Route</h3>
	:This field is only returned if the [[#Level\|Level]] option is set to <code>CarrierRoute</code>.		:This field is only returned if the [[#Level\|Level]] option is set to <code>CarrierRoute</code>.

Admin at 23:57, 7 October 2021

2021-10-07T23:57:40Z

← Older revision		Revision as of 23:57, 7 October 2021
Line 12:		Line 12:

	==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 30:
	!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 174:

	:<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:
			*[[#PostalCode\|PostalCode]]: A 5-digit postal code.
	\|-		\|-
	\|<code>CarrierRoute</code>\|\|		\|<code>CarrierRoute</code>\|\|Two fields are returned for each record:
			*[[#PostalCode\|PostalCode]]: a 5-digit Postal Code
			*[[#CarrierRoute\|CarrierRoute]]: the nearest Carrier Route.
	\|-		\|-
	\|<code>Plus4</code>\|\|		\|<code>Plus4</code>\|\|Two fields are returned for each record:
			*[[#PostalCode\|PostalCode]]: a 9-digit ZIP+4 Postal Code
			*[[#CarrierRoute\|CarrierRoute]]: the nearest Carrier Route.
	\|}		\|}

Line 212:		Line 217:
	\|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 343:		Line 348:

	<h3 class="h3grey">PostalCode</h3>		<h3 class="h3grey">PostalCode</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 355:		Line 362:

	<h3 class="h3grey">CarrierRoute</h3>		<h3 class="h3grey">CarrierRoute</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"

Admin: Admin moved page Reverse GeoCoder:doLookupPostalCodes? to Reverse GeoCoder:doLookupPostalCodes without leaving a redirect: Name Fix

2021-10-07T23:07:59Z

Admin moved page Reverse GeoCoder:doLookupPostalCodes? to Reverse GeoCoder:doLookupPostalCodes without leaving a redirect: Name Fix

← Older revision	Revision as of 23:07, 7 October 2021
(No difference)

Admin at 18:04, 7 October 2021

2021-10-07T18:04:47Z

← Older revision		Revision as of 18:04, 7 October 2021
Line 174:		Line 174:

	:<h4 style="border-bottom:1px solid black;">Level</h4>		:<h4 style="border-bottom:1px solid black;">Level</h4>
	::This ~~options~~ specifies the level of data to search.		::This option specifies the level of data to search.

	::{\| class="alternate01 sortable"		::{\| class="alternate01 sortable"

Admin: Created page with "{{ReverseGeoCoderNav |InputOutputCollapse= }} {{CustomTOC}} The doLookupPostalCodes endpoint returns Postal Codes within a specified radius. =Request= A request consists of..."

2021-10-07T18:02:25Z

Created page with "{{ReverseGeoCoderNav |InputOutputCollapse= }} {{CustomTOC}} The doLookupPostalCodes endpoint returns Postal Codes within a specified radius. =Request= A request consists of..."

New page

{{ReverseGeoCoderNav
|InputOutputCollapse=
}}

{{CustomTOC}}
The doLookupPostalCodes endpoint returns Postal Codes 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==
{{URL-ReverseGeoCoder-doLookupPostalCodes?}}
==Header==
HTTP headers need to match the protocols and formats being used.

Reverse GeoCoder requires the values of <code>Content-Type</code> and <code>Accept</code>.

===Example JSON Request Header===
<pre>{
"Content-Type": "application/json; charset=utf-8",
"Accept": "application/json"
}</pre>

==Field Names==
This is a list of the request field names and their protocol naming conventions.

{| class="alternate01 sortable"
!Field Name !! Level !! REST !! JSON
|-
|Transmission Reference||rowspan="8" valign="center"|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.

<h3 class="h3grey">Transmission Reference</h3>
:''Optional.''

:This is a string value that serves as a unique identifier for this set of records. It is returned as sent.

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"TransmissionReference":"'''''string'''''"</code>
|-
|REST||<code>?t = '''''string'''''</code>
|-
|XML||<code><TransmissionReference>'''''string'''''</TransmissionReference></code>
|}

<h3 class="h3grey">License Key</h3>
:''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.

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"CustomerID":"'''''string'''''"</code>
|-
|REST||<code>&id = '''''string'''''</code>
|-
|XML||<code><CustomerID>'''''string'''''</CustomerID></code>
|}

<h3 class="h3grey">Latitude</h3>
:''Required.''

:The latitude geographic coordinate in decimal format.

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"Latitude":"'''''string'''''"</code>
|-
|REST||<code>&lat = '''''string'''''</code>
|-
|XML||<code><Latitude>'''''string'''''</Latitude></code>
|}

<h3 class="h3grey">Longitude</h3>
:''Required.''

:The longitude geographic coordinate in decimal format.

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"Longitude":"'''''string'''''"</code>
|-
|REST||<code>&long = '''''string'''''</code>
|-
|XML||<code><Longitude>'''''string'''''</Longitude></code>
|}

<h3 class="h3grey">MaxDistance</h3>
:''Optional.''

:The requested maximum distance (in miles). The maximum possible distance is 10 miles. If no MaxDistance is specified, the default is 10 miles.

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"MaxDistance":"'''''string'''''"</code>
|-
|REST||<code>&dist = '''''string'''''</code>
|-
|XML||<code><MaxDistance>'''''string'''''</MaxDistance></code>
|}

<h3 class="h3grey">MaxRecords</h3>
:''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.

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"MaxRecords":"'''''string'''''"</code>
|-
|REST||<code>&recs = '''''string'''''</code>
|-
|XML||<code><MaxRecords>'''''string'''''</MaxRecords></code>
|}

<h3 style="background-color:rgb(240,240,240);">Options</h3>
:''Optional.''

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

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"Options":"'''''string'''''"</code>
|-
|REST||<code>?opt = '''''string'''''</code>
|-
|XML||<code><Options>'''''string'''''</Options></code>
|}

:List options in the following format, with multiple options delimited with a ";".

:{| class="alternate01"
!Syntax
|-
|<code>''OptionName'':''Parameter'';''OptionName'':''Parameter''</code>
|}

:<h4 style="border-bottom:1px solid black;">Level</h4>
::This options specifies the level of data to search.

::{| class="alternate01 sortable"
!Option Name !! Parameter !! Description
|-
|rowspan="3"|'''Level'''||<code>PostalCode</code>||'''''Default.'''''
|-
|<code>CarrierRoute</code>||
|-
|<code>Plus4</code>||
|}

<h3 class="h3grey">Format</h3>
:''Optional.''

:The desired format of the response. Possible values for this option are "json" or "xml". The default value is "xml".

:{| class="alternate01"
!Protocol !! Syntax
|-
|REST||<code>&format = '''''string'''''</code>
|}

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

{| class="alternate01 sortable"
!Field Name !! Level !! JSON/XML
|-
|Version||rowspan="5" valign="center"|Response (Base)||Version
|-
|Transmission Reference||TransmissionReference
|-
|Transmission Results||TransmissionResults
|-
|Results||Results
|-
|Total Records||TotalRecords
|-
|Records||rowspan="8" valign="center"|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.

<h3 class="h3grey">Version</h3>
:This is a string value that is the current revision number of Reverse GeoCoder.

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"Version":"'''''string'''''"</code>
|-
|XML||<code><Version>'''''string'''''</Version></code>
|}

<h3 class="h3grey">Transmission Reference</h3>
: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.

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"TransmissionReference":"'''''string'''''"</code>
|-
|XML||<code><TransmissionReference>'''''string'''''</TransmissionReference></code>
|}

<h3 class="h3grey">Transmission Results</h3>
: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 [[Result Code Details#Reverse GeoCoder|Reverse GeoCoder Result Codes]].

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"TransmissionResults":"'''''string'''''"</code>
|-
|XML||<code><TransmissionResults>'''''string'''''</TransmissionResults></code>
|}

<h3 class="h3grey">Results</h3>
: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 [[Result Code Details#Reverse GeoCoder|Reverse GeoCoder Result Codes]].

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"Results":"'''''string'''''"</code>
|-
|XML||<code><Results>'''''string'''''</Results></code>
|}

<h3 class="h3grey">Total Records</h3>
:Displays the total number of records returned.

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"TotalRecords":"'''''string'''''"</code>
|-
|XML||<code><TotalRecords>'''''string'''''</TotalRecords></code>
|}

==Response Record Elements==
JSON will only contain the Records element.

:{| class="alternate01"
!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.

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

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"City":"'''''string'''''"</code>
|-
|XML||<code><City>'''''string'''''</City></code>
|}

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

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"State":"'''''string'''''"</code>
|-
|XML||<code><State>'''''string'''''</State></code>
|}

<h3 class="h3grey">PostalCode</h3>
:Returns the Postal Code of the output address.

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"PostalCode":"'''''string'''''"</code>
|-
|XML||<code><PostalCode>'''''string'''''</PostalCode></code>
|}

<h3 class="h3grey">CarrierRoute</h3>
:Returns the carrier route for an address if the <code>Level</code> option is set to <code>CarrierRoute</code>.

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"CarrierRoute":"'''''string'''''"</code>
|-
|XML||<code><CarrierRoute>'''''string'''''</CarrierRoute></code>
|}

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

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"Latitude":"'''''string'''''"</code>
|-
|XML||<code><Latitude>'''''string'''''</Latitude></code>
|}

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

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"Longitude":"'''''string'''''"</code>
|-
|XML||<code><Longitude>'''''string'''''</Longitude></code>
|}

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

:{| class="alternate01"
!Protocol !! Syntax
|-
|JSON||<code>"Distance":"'''''string'''''"</code>
|-
|XML||<code><Distance>'''''string'''''</Distance></code>
|}

[[Category:Reverse GeoCoder]]
[[Category:Reference]]

← Older revision		Revision as of 23:59, 7 October 2021
Line 180:		Line 180:
	\|-		\|-
	\|rowspan="3"\|'''Level'''\|\|<code>PostalCode</code>\|\|'''''Default.''''' A single field is returned for each record:		\|rowspan="3"\|'''Level'''\|\|<code>PostalCode</code>\|\|'''''Default.''''' A single field is returned for each record:
	*[[#~~PostalCode~~\|PostalCode]]: A 5-digit postal code.		*[[#Postal Code\|PostalCode]]: A 5-digit postal code.
	\|-		\|-
	\|<code>CarrierRoute</code>\|\|Two fields are returned for each record:		\|<code>CarrierRoute</code>\|\|Two fields are returned for each record:
	*[[#~~PostalCode~~\|PostalCode]]: a 5-digit Postal Code		*[[#Postal Code\|PostalCode]]: a 5-digit Postal Code
	*[[#~~CarrierRoute~~\|CarrierRoute]]: the nearest Carrier Route.		*[[#Carrier Route\|CarrierRoute]]: the nearest Carrier Route.
	\|-		\|-
	\|<code>Plus4</code>\|\|Two fields are returned for each record:		\|<code>Plus4</code>\|\|Two fields are returned for each record:
	*[[#~~PostalCode~~\|PostalCode]]: a 9-digit ZIP+4 Postal Code		*[[#Postal Code\|PostalCode]]: a 9-digit ZIP+4 Postal Code
	*[[#~~CarrierRoute~~\|CarrierRoute]]: the nearest Carrier Route.		*[[#Carrier Route\|CarrierRoute]]: the nearest Carrier Route.
	\|}		\|}