Parserator Parse addresses, names & more

API

If you are interested in parsing addresses or names, try our easy to use API.

Your first 1,000 API calls are free. See our pricing for more details.

All calls require an API key. To get one, contact DataMade info@datamade.us.

API Endpoints

A few things to know:

usaddress can parse any unstructured address in the United States into tagged address components. It uses the usaddress python library. Read the library documentation.

Query parameters

All query parameters are required.

Parameter Description
address Unstructured input address to parse
api_key Customer API key (GUID). To get a key, contact DataMade info@datamade.us

Response

Returns a JSON object with:

Parameter Description
meta
Parameter Description
status ok or error
status_code
Status code Description
Successful request
Address is not parseable or input data is missing or format is invalid
An invalid or expired api_key was used in the call
Unexpected service error. contact us if you encounter this info@datamade.us
message More details if an error occurred
parser Parser used for processing (usaddress)
input_address Submitted address
type

Identified address type.

  • Street Address
  • Intersection
  • PO Box
  • Ambiguous
result

JSON object of parsed address parts (value) with an assigned tag. Below is the full list of available tags:

Tag Description
AddressNumber address number
AddressNumberPrefix a modifier before an address number, e.g. ‘Mile’, ‘#’
AddressNumberSuffix a modifier after an address number, e.g ‘B’, ‘1/2’
BuildingName the name of a building, e.g. ‘Atlanta Financial Center’
CornerOf words indicating that an address is a corner, e.g. ‘Junction’, ‘corner of’
IntersectionSeparator a conjunction connecting parts of an intersection, e.g. ‘and’, ‘&’
LandmarkName the name of a landmark, e.g. ‘Wrigley Field’, ‘Union Station’
NotAddress a non-address component that doesn’t refer to a recipient
OccupancyIdentifier the identifier of an occupancy, often a number or letter
OccupancyType a type of occupancy within a building, e.g. ‘Suite’, ‘Apt’, ‘Floor’
PlaceName city
Recipient a non-address recipient, e.g. the name of a person/organization
StateName state
StreetName street name, excluding type & direction
StreetNamePostDirectional a direction after a street name, e.g. ‘North’, ‘S’
StreetNamePostType a street type that comes after a street name, e.g. ‘Avenue’, ‘Rd’
StreetNamePreDirectional a direction before a street name, e.g. ‘North’, ‘S’
StreetNamePreModifier a modifier before a street name that is not a direction, e.g. ‘Old’
StreetNamePreType a street type that comes before a street name, e.g. ‘Route’, ‘Ave’
SubaddressIdentifier the name/identifier of a subaddress component
SubaddressType a level of detail in an address that is not an occupancy within a building, e.g. ‘Building’, ‘Tower’
USPSBoxGroupID the identifier of a USPS box group, usually a number
USPSBoxGroupType a name for a group of USPS boxes, e.g. ‘RR’
USPSBoxID the identifier of a USPS box, usually a number
USPSBoxType a USPS box, e.g. ‘P.O. Box’
ZipCode zip code

Example

Let’s parse 123 main st, Chicago IL

https://parserator.datamade.us/api/usaddress/?address=123%20main%20st,%20Chicago%20IL&api_key=B525F776-DC99-11E4-A50F-0E97B6C90E9A

Response

{
   "meta":{
      "status":"ok",
      "status_code":200,
      "message":"",
      "parser":"usaddress",
      "input_address":"123 main st, Chicago IL"
   },
   "type":"Street Address",
   "result":[
      {
         "tag":"AddressNumber",
         "value":"123"
      },
      {
         "tag":"StreetName",
         "value":"main"
      },
      {
         "tag":"StreetNamePostType",
         "value":"st"
      },
      {
         "tag":"PlaceName",
         "value":"Chicago"
      },
      {
         "tag":"StateName",
         "value":"IL"
      }
   ]
}

probablepeople can parse any unstructured western name into tagged name components. It uses the probablepeople python library. Read the library documentation.

This parser can also identify individuals, couples and company names, since they're often mixed with person names in real world datasets.

Query parameters

All query parameters are required.

Parameter Description
name Unstructured input name to parse
api_key Customer API key (GUID). To get a key, contact DataMade info@datamade.us

Response

Returns a JSON object with:

Parameter Description
meta
Parameter Description
status ok or error
status_code
Status code Description
Successful request
Name is not parseable or input data is missing or format is invalid
An invalid or expired api_key was used in the call
Unexpected service error. contact us if you encounter this info@datamade.us
message More details if an error occurred
parser Parser used for processing (probablepeople)
input_name Submitted name
type

Identified name type.

  • Person - an individual
  • Household - a couple
  • Corporation - a legal entity, such as a company, organization or government
result

JSON object of parsed name parts (value) with an assigned tag. Below is the full list of available tags:

  • PrefixMarital
  • PrefixOther
  • GivenName
  • FirstInitial
  • MiddleName
  • MiddleInitial
  • Surname
  • LastInitial
  • SuffixGenerational
  • SuffixOther
  • Nickname
  • And
  • CorporationName
  • CorporationNameOrganization
  • CorporationLegalType
  • CorporationNamePossessiveOf
  • ShortForm
  • ProxyFor
  • AKA

Example

Let’s parse Mr George 'Gob' Bluth II

https://parserator.datamade.us/api/probablepeople/?name=Mr George 'Gob' Bluth II&api_key=B525F776-DC99-11E4-A50F-0E97B6C90E9A

Response

{
   "meta":{
      "status":"ok",
      "status_code":200,
      "message":"",
      "parser":"probablepeople",
      "input_name":"Mr George 'Gob' Bluth II"
   },
   "type":"Person",
   "result" : [ { "tag" : "PrefixMarital",
        "value" : "Mr"
      },
      { "tag" : "GivenName",
        "value" : "George"
      },
      { "tag" : "Nickname",
        "value" : "'Gob'"
      },
      { "tag" : "Surname",
        "value" : "Bluth"
      },
      { "tag" : "SuffixGenerational",
        "value" : "II"
      }
    ]
}

Query parameters

All query parameters are required.

Parameter Default value Description
api_key Required. Customer API key (GUID). To get a key, contact DataMade info@datamade.us
start_date 30 days ago from the current date and time Optional. Start date for querying usage. Expects a date in UTC ISO 8601 format (example: 2015-04-12T18:51:19).
end_date The current date and time Required. End date for querying usage. Expects a date in UTC ISO 8601 format (example: 2015-04-12T18:51:19).

Response

Returns a JSON object with:

Parameter Description
meta
Parameter Description
status ok or error
status_code
Status code Description
Successful request
Input data is missing or format is invalid
An invalid or expired api_key was used in the call
Unexpected service error. contact us if you encounter this info@datamade.us
message More details if an error occurred
start_date Submitted end date
end_date Submitted end date
api_calls_made

Numer of API calls made between the two dates.

Example

Let’s parse 123 main st, Chicago IL

https://parserator.datamade.us/api/usage/?api_key=B525F776-DC99-11E4-A50F-0E97B6C90E9A&start_date=2015-04-10&end_date=2015-04-10

Response

{
   "meta":{
      "status":"ok",
      "status_code":200,
      "message":"",
      "start_date":"2015-04-10T00:00:00",
      "end_date":"2015-04-10T00:00:00"
   },
   "api_calls_made":0
}

Report a Bad Parse

If a parser failed to tag something correctly, please report it here. We will use your information to improve our models.

Pricing

Your first 1,000 API calls are free. After that, we charge per month based on your usage.

All calls require an API key. To get one, contact DataMade info@datamade.us.

Name API call limit / month Price / month (USD)
Juniper 5,000 $10.00
Oak 10,000 $15.00
Spruce 20,000 $20.00
Douglas Fir 50,000 $50.00
Redwood Custom Contact us! info@datamade.us