Difference between revisions of "XcelDataAPI:Version 0.2/standardize-address"

From XcelData Wiki
Jump to: navigation, search
 
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
  
−
== Main Entry Point ==
+
This endpoint allows you to correct up to five U.S. Mailing Addresses (via USPS) per request.
−
{{main|XcelDataAPI:Version_0.2|XcelData API v0.2}}
 
  
−
== Example ==
+
All request urls listed are relative of the [[XcelDataAPI:Version_0.2|XDAPI v0.2 base url]].
−
This endpoint allows you to query multiple addresses at the same time.
 
  
−
Let's look up the work address currently located at: '''2118 F St, Bakersfield, CA 93301''' and the old address located at: '''5880 District Blvd Ste 5, Bakersfield, CA 93301'''
+
== Request ==
 +
 
 +
The incoming request must be a POST request and will accept various content-types:
 +
 
 +
=== text/xml or application/json ===
 +
Submit the entire XML or JSON blob directly into the request body.
  
−
== Request ==
+
<pre><Requests>
 +
  <Request ID="1">
 +
    <Address1> ...</pre>
 +
 
 +
=== application/x-www-form-urlencoded ===
 +
URL-Encode the XML or JSON blob and submit under the name/key "data"
 +
<pre>data=%3CRequests%3E%0D%0A%20%20%3CRequest%20ID%3D%221%22%3E%0D%0A%20%20%20%20%3CAddress1%3E ...</pre>
 +
 
 +
===Examples===
 +
<pre>
 +
//post:
 +
curl -d "data=%3CRequests%3E%0D%0A%20%20%3CRequest%20ID%3D%221%22%3E%0D%0A%20%20%20%20%3CAddress1%3E ..." -X POST https://api.xceldata.com/0.2/xml/1E17162A-8355-4FF2-8DCD-E5CEE676FD93/standardize-address
 +
 
 +
//post application/json:
 +
curl -d '{"Requests":[{"ID":1, ...' -H "Content-Type: application/json" -X POST https://api.xceldata.com/0.2/xml/1E17162A-8355-4FF2-8DCD-E5CEE676FD93/standardize-address
  
−
The incoming request can be in either XML or JSON format and should be post data (or alternatively if using application/x-www-form-urlencoded use the key "data" and pass it the xml or json as a string).
+
//post using a data file:
 +
curl -d "@data.xml" -X POST https://api.xceldata.com/0.2/xml/1E17162A-8355-4FF2-8DCD-E5CEE676FD93/standardize-address
 +
</pre>
  
 +
== Example Requests ==
 
{|
 
{|
 
|-
 
|-
Line 38: Line 58:
 
{"Requests": [
 
{"Requests": [
 
   {
 
   {
 +
    "ID": 1,
 
     "Address1": "2118 F St",
 
     "Address1": "2118 F St",
 
     "City": "Bakersfield",
 
     "City": "Bakersfield",
−
    "ID": 1,
 
 
     "State": "CA",
 
     "State": "CA",
 
     "Zip5": 93301
 
     "Zip5": 93301
 
   },
 
   },
 
   {
 
   {
 +
    "ID": 2,
 
     "Address1": "5880 District Blvd Ste 5",
 
     "Address1": "5880 District Blvd Ste 5",
 
     "City": "Bakersfield",
 
     "City": "Bakersfield",
−
    "ID": 1,
 
 
     "State": "CA",
 
     "State": "CA",
 
     "Zip5": 93313
 
     "Zip5": 93313
Line 56: Line 76:
 
|}
 
|}
  
−
== Request Format ==
+
=== Request Format ===
 +
 
 +
Lifted from '''Address Information USPS Web Tools™ Application Programming Interface User’s Guide Document Version 4.2 (02/13/2018)''':
 +
 
 +
{{alert|Heads up:|'''Address1''' and '''Address2''' can be used interchangeably. USPS doesn't care if they get swapped so don't worry on being strict with the format.|info}}
 +
 
 
<table class="wikitable">
 
<table class="wikitable">
 
   <tr>
 
   <tr>
Line 195: Line 220:
 
   </tr>
 
   </tr>
 
</table>
 
</table>
 +
 +
=== Test ===
 +
 +
You can test either examples directly in your browser (you will need to paste the request in the box on the link below):
 +
 +
* [https://api.xceldata.com/0.2/xml/1E17162A-8355-4FF2-8DCD-E5CEE676FD93/standardize-address Test XML Output]
 +
* [https://api.xceldata.com/0.2/json/1E17162A-8355-4FF2-8DCD-E5CEE676FD93/standardize-address Test JSON Output]
  
 
== Output==
 
== Output==
Line 257: Line 289:
 
</pre>
 
</pre>
 
|}
 
|}
−
 
−
== Test ==
 
−
 
−
You can use either request methods at either of these links:
 
−
 
−
* [https://api.xceldata.com/0.2/xml/1E17162A-8355-4FF2-8DCD-E5CEE676FD93/standardize-address Test XML Output]
 
−
* [https://api.xceldata.com/0.2/json/1E17162A-8355-4FF2-8DCD-E5CEE676FD93/standardize-address Test JSON Output]
 

Latest revision as of 16:28, 1 May 2018

This endpoint allows you to correct up to five U.S. Mailing Addresses (via USPS) per request.

All request urls listed are relative of the XDAPI v0.2 base url.

Request

The incoming request must be a POST request and will accept various content-types:

text/xml or application/json

Submit the entire XML or JSON blob directly into the request body. 

<Requests>
  <Request ID="1">
    <Address1> ...

application/x-www-form-urlencoded

URL-Encode the XML or JSON blob and submit under the name/key "data" 

data=%3CRequests%3E%0D%0A%20%20%3CRequest%20ID%3D%221%22%3E%0D%0A%20%20%20%20%3CAddress1%3E ...

Examples

//post:
curl -d "data=%3CRequests%3E%0D%0A%20%20%3CRequest%20ID%3D%221%22%3E%0D%0A%20%20%20%20%3CAddress1%3E ..." -X POST https://api.xceldata.com/0.2/xml/1E17162A-8355-4FF2-8DCD-E5CEE676FD93/standardize-address

//post application/json:
curl -d '{"Requests":[{"ID":1, ...' -H "Content-Type: application/json" -X POST https://api.xceldata.com/0.2/xml/1E17162A-8355-4FF2-8DCD-E5CEE676FD93/standardize-address

//post using a data file:
curl -d "@data.xml" -X POST https://api.xceldata.com/0.2/xml/1E17162A-8355-4FF2-8DCD-E5CEE676FD93/standardize-address

Example Requests

XML - /0.2/xml/api-key/standardize-address JSON - /0.2/json/api-key/standardize-address 
<Requests>
  <Request ID="1">
    <Address1>2118 F St</Address1>
    <City>Bakersfield</City>
    <State>CA</State>
    <Zip5>93301</Zip5>
  </Request>
  <Request ID="2">
    <Address1>5880 District Blvd Ste 5</Address1>
    <City>Bakersfield</City>
    <State>CA</State>
    <Zip5>93313</Zip5>
  </Request>
</Requests>

{"Requests": [
  {
    "ID": 1,
    "Address1": "2118 F St",
    "City": "Bakersfield",
    "State": "CA",
    "Zip5": 93301
  },
  {
    "ID": 2,
    "Address1": "5880 District Blvd Ste 5",
    "City": "Bakersfield",
    "State": "CA",
    "Zip5": 93313
  }
]}

Request Format

Lifted from Address Information USPS Web Tools™ Application Programming Interface User’s Guide Document Version 4.2 (02/13/2018):


Heads up: Address1 and Address2 can be used interchangeably. USPS doesn't care if they get swapped so don't worry on being strict with the format.

Address1

Required Tag/

Optional Value

Address Line 1 is used to provide an apartment or suite number, if applicable. Maximum characters allowed: 38

For example: <Address1></Address1>

Address2

Required Tag/

Required Value

Street address.

Maximum characters allowed: 38

For example: <Address2>6406 Ivy </Address2>

City

Required Tag/

Optional Value

(see box at right)

Maximum characters allowed: 15.Either <City> and <State> or <Zip5> are required.

For example: <City> Greenbelt </City>

State

Required Tag/

Optional Value

(see box at right)

Maximum characters allowed: 2. Either <City> and <State> or <Zip5> are required.

For example: <State>MD</State>

Zip5

Required Tag/

Optional Value

(see box at right)

Input tag exactly as presented, not all caps.Maximum characters allowed: 5. Either <City> and <State> or <Zip5> are required.

For example: <Zip5></Zip5>

Zip4

Required Tag/

Optional Value

Input tag exactly as presented, not all caps. Maximum characters allowed: 4

For example: <Zip4></Zip4>

Test

You can test either examples directly in your browser (you will need to paste the request in the box on the link below):

Output

The output can either be XML or JSON. You specify that in the request url.

XML - /0.2/xml/api-key/standardize-address JSON - /0.2/json/api-key/standardize-address 
<?xml version="1.0"?>
<root>
  <success>1</success>
  <Results>
    <Result ID="1">
      <ID>1</ID>
      <Address1>2118 F ST</Address1>
      <City>BAKERSFIELD</City>
      <State>CA</State>
      <Zip5>93301</Zip5>
      <Zip4>3826</Zip4>
    </Result>
    <Result ID="2">
      <ID>2</ID>
      <Address1>5880 DISTRICT BLVD</Address1>
      <Address2>STE 5</Address2>
      <City>BAKERSFIELD</City>
      <State>CA</State>
      <Zip5>93313</Zip5>
      <Zip4>2138</Zip4>
    </Result>
  </Results>
</root>

{
  "success": true,
  "Results": [
    {
      "ID": "1",
      "Address1": "2118 F ST",
      "City": "BAKERSFIELD",
      "State": "CA",
      "Zip5": "93301",
      "Zip4": "3826"
    },
    {
      "ID": "2",
      "Address1": "5880 DISTRICT BLVD",
      "Address2": "STE 5",
      "City": "BAKERSFIELD",
      "State": "CA",
      "Zip5": "93313",
      "Zip4": "2138"
    }
  ]
}
Retrieved from "https://wiki.dev.xceldata.com/index.php?title=XcelDataAPI:Version_0.2/standardize-address&oldid=206"