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

From XcelData Wiki
Jump to: navigation, search
 
(9 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 55: Line 75:
  
 
|}
 
|}
 +
 +
=== 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">
 +
  <tr>
 +
      <td>
 +
          <p class="tablecontent"><span><span>Address1</span></span>
 +
          </p>
 +
      </td>
 +
      <td>
 +
          <p class="tablecontent"><span>Required Tag/</span></p>
 +
          <p class="tablecontent"><span>Optional Value</span></p>
 +
      </td>
 +
      <td>
 +
          <p class="tablecontent"><span><span>Address Line 1 is
 +
used to provide an apartment or suite number, if applicable.<span></span></span>
 +
              </span><span style="mso-bookmark:          _Toc476379563;"><span>Maximum characters
 +
allowed: 38</span></span>
 +
          </p>
 +
          <p class="code"><span><b><span>For
 +
example:</span></b>
 +
              <Address1></Address1>
 +
              </span>
 +
          </p>
 +
      </td>
 +
  </tr>
 +
  <tr>
 +
      <td>
 +
          <p class="tablecontent"><span><span>Address2</span></span>
 +
          </p>
 +
      </td>
 +
      <td>
 +
          <p class="tablecontent"><span>Required Tag/</span></p>
 +
          <p class="tablecontent"><span>Required Value</span></p>
 +
      </td>
 +
      <td>
 +
          <p class="tablecontent"><span><span>Street address.</span></span>
 +
          </p>
 +
          <p class="tablecontent"><span><span>Maximum characters allowed: 38</span></span>
 +
          </p>
 +
          <p class="code"><span><b><span>For
 +
example:</span></b>
 +
              <Address2>6406 Ivy </Address2>
 +
              </span>
 +
          </p>
 +
      </td>
 +
  </tr>
 +
  <tr>
 +
      <td>
 +
          <p class="tablecontent"><span><span>City</span></span>
 +
          </p>
 +
      </td>
 +
      <td>
 +
          <p class="tablecontent"><span>Required Tag/</span></p>
 +
          <p class="tablecontent"><span>Optional Value</span></p>
 +
          <p class="tablecontent"><span>(see box at
 +
right)</span></p>
 +
      </td>
 +
      <td>
 +
          <p class="tablecontent"><span><span>Maximum characters allowed: 15.<span></span></span>Either
 +
              <City> and
 +
                  <State> <b><i>or</i></b>
 +
                      <Zip5> are required.</span>
 +
          </p>
 +
          <p class="code"><span><b><span>For
 +
example:</span></b>
 +
              <City> Greenbelt </City>
 +
              </span>
 +
          </p>
 +
      </td>
 +
  </tr>
 +
  <tr>
 +
      <td>
 +
          <p class="tablecontent"><span><span>State</span></span>
 +
          </p>
 +
      </td>
 +
      <td>
 +
          <p class="tablecontent"><span>Required Tag/</span></p>
 +
          <p class="tablecontent"><span>Optional Value</span></p>
 +
          <p class="tablecontent"><span>(see box at
 +
right)</span></p>
 +
      </td>
 +
      <td>
 +
          <p class="tablecontent"><span><span>Maximum characters allowed: 2. Either</span>
 +
              <City> and
 +
                  <State> <b><i style="mso-bidi-font-style:normal;">or</i></b>
 +
                      <Zip5> are required.</span>
 +
          </p>
 +
          <p class="code"><span><b><span>For
 +
example:</span></b>
 +
              <State>MD</State>
 +
              </span>
 +
          </p>
 +
      </td>
 +
  </tr>
 +
  <tr>
 +
      <td>
 +
          <p class="tablecontent"><span><span>Zip5</span></span>
 +
          </p>
 +
      </td>
 +
      <td>
 +
          <p class="tablecontent"><span>Required Tag/</span></p>
 +
          <p class="tablecontent"><span>Optional Value</span></p>
 +
          <p class="tablecontent"><span>(see box at right)</span></p>
 +
      </td>
 +
      <td>
 +
          <p class="tablecontent"><span><span>Input <b>tag</b>  exactly as presented, not all caps.<span></span></span>Maximum characters allowed: 5. Either
 +
              <City> and
 +
                  <State> <b><i style="mso-bidi-font-style:normal;">or</i></b>
 +
                      <Zip5> are required.</span>
 +
          </p>
 +
          <p class="tablecontent"><span><b><span>For example:<span></span></span>
 +
              </b>
 +
              </span><span><span class="codeChar"><span><Zip5></Zip5></span></span>
 +
              </span><span><span style="font-family:&quot;Courier New&quot;;            mso-bidi-font-family:&quot;Times New Roman&quot;;"></span></span>
 +
          </p>
 +
      </td>
 +
  </tr>
 +
  <tr>
 +
      <td>
 +
          <p class="tablecontent"><span><span>Zip4</span></span>
 +
          </p>
 +
      </td>
 +
      <td>
 +
          <p class="tablecontent"><span>Required Tag/</span></p>
 +
          <p class="tablecontent"><span>Optional Value</span></p>
 +
      </td>
 +
      <td>
 +
          <p class="tablecontent"><span><span>Input <b>tag</b> exactly as presented, not all
 +
caps.<span></span></span>
 +
              </span><span><span>Maximum
 +
characters allowed: 4</span></span>
 +
          </p>
 +
          <p class="code"><span><span class="tablecontentChar"><b><span>For example:</span></b>
 +
              </span><span> </span>
 +
              <Zip4></Zip4>
 +
              </span>
 +
          </p>
 +
      </td>
 +
  </tr>
 +
</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 117: Line 289:
 
</pre>
 
</pre>
 
|}
 
|}
−
 
−
== Test ==
 
−
 
−
You can use either request method 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"