Parse an address

v1.0.0

The address-recognition API makes it easy for you to extract address data from unstructured text, including the recipient name, line 1, line 2, city, postal code, and more.

Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's address-recognition API helps you extract meaningful, structured data from this unstructured text. The parsed address data is returned in the same structure that's used for other ShipEngine APIs, such as address validation, rate quotes, and shipping labels.

Note: Address recognition is currently supported for the United States, Canada, Australia, New Zealand, the United Kingdom, and Ireland.

Input

{
  "type": "object",
  "description": "The only required field is `text`, which is the text to be parsed. You can optionally also provide an `address` containing already-known values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines.\n",
  "required": [
    "text"
  ],
  "properties": {
    "address": {
      "description": "You can optionally provide any already-known address values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines.\n",
      "type": "object"
    },
    "text": {
      "type": "string",
      "description": "The unstructured text that contains address-related entities"
    }
  },
  "additionalProperties": false
}

Output

{
  "type": "object",
  "description": "The parsed address, as well as a confidence score and a list of all the entities that were recognized in the text.\n",
  "required": [
    "address",
    "entities",
    "score"
  ],
  "properties": {
    "address": {
      "description": "The parsed address.  This address may not be complete, depending on how much information was included in the text and how confident the API is about each recognized entity.\n\n> **Note:** The address-recognition API does not currently perform any validation of the parsed address, so we recommend that you use the [address-validation API](https://www.shipengine.com/docs/addresses/validation/) to ensure that the address is correct.\n",
      "type": "object"
    },
    "entities": {
      "type": "array",
      "description": "All of the entities that were recognized in the text. An \"entity\" is a single piece of data, such as a city, a postal code, or an address line.  Each entity includes the original text and the parsed value.\n",
      "items": {
        "type": "object",
        "description": "An entity is a single piece of data that was recognized in unstructured text.  For example, a city, a postal code, package dimensions, insured value, etc.  Each entity includes the original text and the parsed value.\n",
        "required": [
          "type",
          "score",
          "text",
          "start_index",
          "end_index"
        ],
        "properties": {
          "end_index": {
            "type": "integer",
            "description": "The index of the last character of this entity within the original text"
          },
          "result": {
            "type": "object",
            "description": "The normalized value of the entity.\n\nMost entity results have a `value` field, which is the normalized value of the entity.  For example, if the substring \"john doe\" was recognized as a \"person\" entity, then the value might be normalized to have proper capitalization (e.g. \"John Doe\").  Or if the substring \"ft worth\" was recognized as a \"city\" entity, then the value might be normalized to \"Fort Worth\".\n\nSome entities have other information in addition to, or instead of a `value`.  For example, a \"dimensions\" entity will have separate fields for `length`, `width`, `height`, and `unit`.\n",
            "properties": {}
          },
          "score": {
            "type": "number",
            "format": "double",
            "description": "A confidence score between zero and one that indicates how certain the API is that it correctly recognized this entity\n"
          },
          "start_index": {
            "type": "integer",
            "description": "The index of the first character of this entity within the original text"
          },
          "text": {
            "type": "string",
            "description": "The substring from the original text that was recognized as this entity"
          },
          "type": {
            "type": "string",
            "description": "The Entity type (e.g. \"weight\", \"person\", \"address_line1\", etc.)"
          }
        },
        "additionalProperties": false
      }
    },
    "score": {
      "type": "number",
      "format": "double",
      "description": "A confidence score between zero and one that indicates how certain the API is that it understood the text.\n"
    }
  },
  "additionalProperties": false
}