> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.goshippo.com/feedback

```json
{
  "path": "/docs/AddressAPI/address_parser",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# Address parser

> Convert an address string into a structured address object using the Shippo Addresses API parser.

export const AddressParserDemo = () => {
  const {useState, useCallback} = React;
  const BTN_GREEN = '#97C38E';
  const TAB_ACTIVE = '#30881E';
  const BORDER = '#e0e0e0';
  const ADDRESS_FIELDS = ['address_line_1', 'address_line_2', 'city_locality', 'state_province', 'postal_code', 'country_code', 'email', 'phone'];
  const parserAddresses = [{
    label: 'Sample US address',
    address: '2900 W Winn Rd, Niles, Michigan, 49120, US',
    response: {
      address_line_1: '2900 W WINN RD',
      city_locality: 'NILES',
      state_province: 'MICHIGAN',
      postal_code: '49120',
      country_code: 'US'
    }
  }, {
    label: 'Sample US address \u2013 With phone and email',
    address: '2900 W Winn Rd Niles Michigan 49120 US tom@mymail.com 3472226190',
    response: {
      email: 'tom@mymail.com',
      phone: '3472226190',
      address_line_1: '2900 W WINN RD',
      city_locality: 'NILES',
      state_province: 'MICHIGAN',
      postal_code: '49120',
      country_code: 'US'
    }
  }, {
    label: 'Sample International address',
    address: '68 Drumcondra Road Upper, Dublin, Co. Dublin, IE, D09 X620',
    response: {
      address_line_1: '68 DRUMCONDRA ROAD UPPER',
      city_locality: 'DUBLIN',
      postal_code: 'D09 X620',
      country_code: 'IE'
    }
  }];
  const [result, setResult] = useState(null);
  const [activeTab, setActiveTab] = useState(0);
  const [selectedIndex, setSelectedIndex] = useState('');
  const [copied, setCopied] = useState(false);
  const handleSubmit = useCallback(index => {
    setResult(parserAddresses[index]);
    setActiveTab(0);
  }, []);
  const handleSelect = e => {
    const v = e.target.value;
    setSelectedIndex(v === '' ? '' : Number(v));
  };
  const handleParse = () => {
    if (selectedIndex !== '') handleSubmit(selectedIndex);
  };
  const handleCopy = () => {
    const text = JSON.stringify(result?.response, null, 2);
    navigator.clipboard?.writeText(text);
    setCopied(true);
    setTimeout(() => setCopied(false), 2000);
  };
  const isDisabled = selectedIndex === '';
  const rows = result ? ADDRESS_FIELDS.map(field => ({
    field,
    value: result.response[field] ?? ''
  })) : [];
  return <div>
      {}
      <div style={{
    display: 'flex',
    gap: '12px',
    alignItems: 'center'
  }}>
        <select value={selectedIndex} onChange={handleSelect} style={{
    flex: 1,
    padding: '10px 14px',
    borderRadius: '6px',
    border: `1px solid ${BORDER}`,
    fontSize: '14px',
    backgroundColor: 'var(--bg-color, #fff)',
    color: 'var(--text-color-primary, #1F2D34)'
  }}>
          <option value="">Choose Sample Address</option>
          {parserAddresses.map((opt, i) => <option key={i} value={i}>
              {opt.label}
            </option>)}
        </select>
        <button onClick={handleParse} disabled={isDisabled} style={{
    padding: '12px 16px',
    backgroundColor: BTN_GREEN,
    color: '#fff',
    border: 'none',
    borderRadius: '8px',
    fontSize: '16px',
    fontWeight: 'bold',
    cursor: isDisabled ? 'default' : 'pointer',
    whiteSpace: 'nowrap',
    transition: 'background-color 0.2s'
  }}>
          Parse
        </button>
      </div>

      {}
      <div style={{
    marginTop: '16px'
  }}>
        <div style={{
    display: 'flex',
    borderBottom: `2px solid ${BORDER}`
  }}>
          {['Parsed Address', 'API Response'].map((tab, i) => <button key={tab} onClick={() => setActiveTab(i)} style={{
    padding: '8px 20px',
    border: 'none',
    background: 'none',
    fontSize: '14px',
    fontWeight: activeTab === i ? 500 : 'normal',
    color: activeTab === i ? TAB_ACTIVE : '#666',
    borderBottom: activeTab === i ? `2px solid ${TAB_ACTIVE}` : '2px solid transparent',
    cursor: 'pointer',
    marginBottom: '-2px',
    textTransform: 'uppercase'
  }}>
              {tab}
            </button>)}
        </div>

        {result ? activeTab === 0 ? <div style={{
    border: `1px solid ${BORDER}`,
    borderRadius: '8px',
    padding: '16px',
    marginTop: '12px',
    display: 'flex',
    flexDirection: 'column',
    gap: '8px'
  }}>
              <h5 style={{
    margin: 0
  }}>Input Address</h5>
              <div style={{
    color: '#555'
  }}>{result.address}</div>
              <table style={{
    width: '100%',
    borderCollapse: 'collapse',
    marginTop: '8px',
    fontSize: '14px'
  }}>
                <colgroup>
                  <col width="12%" />
                  <col width="44%" />
                  <col width="44%" />
                </colgroup>
                <thead>
                  <tr style={{
    borderBottom: `1px solid ${BORDER}`
  }}>
                    <th style={{
    padding: '6px 8px',
    textAlign: 'center'
  }}>
                      Identified
                    </th>
                    <th style={{
    padding: '6px 8px',
    textAlign: 'left'
  }}>
                      Field
                    </th>
                    <th style={{
    padding: '6px 8px',
    textAlign: 'left'
  }}>
                      Value
                    </th>
                  </tr>
                </thead>
                <tbody>
                  {rows.map(({field, value}) => <tr key={field} style={{
    borderBottom: `1px solid ${BORDER}`
  }}>
                      <td style={{
    padding: '6px 8px',
    textAlign: 'center'
  }}>
                        {value ? <span style={{
    color: '#2e7d32',
    fontWeight: 'bold'
  }}>
                            ✓
                          </span> : null}
                      </td>
                      <td style={{
    padding: '6px 8px',
    fontFamily: 'monospace'
  }}>
                        {field}
                      </td>
                      <td style={{
    padding: '6px 8px'
  }}>{value}</td>
                    </tr>)}
                </tbody>
              </table>
            </div> : <div style={{
    position: 'relative',
    marginTop: '12px'
  }}>
              <button onClick={handleCopy} style={{
    position: 'absolute',
    top: '8px',
    right: '8px',
    background: 'rgba(255,255,255,0.15)',
    border: 'none',
    color: '#abb2bf',
    cursor: 'pointer',
    borderRadius: '4px',
    padding: '4px 10px',
    fontSize: '12px'
  }}>
                {copied ? 'Copied!' : 'Copy'}
              </button>
              <pre style={{
    backgroundColor: '#282c34',
    color: '#abb2bf',
    padding: '16px',
    borderRadius: '8px',
    overflowX: 'auto',
    fontSize: '13px',
    margin: 0,
    lineHeight: '1.5'
  }}>
                {JSON.stringify(result.response, null, 2)}
              </pre>
            </div> : <p style={{
    marginTop: '16px',
    color: '#666'
  }}>
            Please select an address and click Parse to get started.
          </p>}
      </div>
    </div>;
};

A parser is a tool for analyzing a string with some predefined rules. Using the Addresses API parser, you can convert a string into a correctly formatted address object.

The parser expects an address string in the following formats.

* For best results, use a comma `,`  as a delimiter.
* Your address must follow this order: `address_line_1`, `address_line_2`, `city_locality`, `state_province`, `postal_code`, `country_code`.
* `phone` and `email` can be in any part of the string.

<CodeGroup>
  ```string Good string example ✅ theme={null}
  11605 W Belleview Ave, Littleton, Colorado, 80127, US
  ```

  ```string Bad string example ❌ theme={null}
  Colorado 11605 W Belleview Ave Littleton 80127 US
  ```
</CodeGroup>

## Parse a string

Follow this example to parse a string to an address object.

<CodeGroup>
  ```json cURL theme={null}
  curl -i -X GET \
    'https://api.goshippo.com/v2/addresses/parse?address=Shippo%20731%20Market%20St%20%23200%2C%20San%20Francisco%2C%20CA%2094103%20US%20shippo%40shippo.com%20%2B1-555-999-8888' \
    -H 'Authorization: ShippoToken <API_TOKEN>'
  ```

  ```json Response theme={null}
  {
      "email": "shippo@shippo.com",
      "phone": "+1-555-999-8888",
      "address_line_1": "731 MARKET ST",
      "address_line_2": "#200",
      "city_locality": "SAN FRANCISCO",
      "state_province": "CA",
      "postal_code": "94103",
      "country_code": "US"
  }
  ```
</CodeGroup>

## Try Address Parser

Use this demo to learn about the Shippo Address Parser. This demo takes an address as an input, and then displays the response from the Address Parser method as visualized content and as a JSON object.

<AddressParserDemo />