API documentation
If you are interested in parsing addresses or names, try our easy to use API.
Your first 2,500 API calls are free. See our pricing for more details.
All calls require an API key.
A few things to know
- All API calls should be made with
HTTP GETorPOST - All API calls are made over an HTTPS connection
- All API responses are in JSON format
- All methods are accessed via: https://parserator.datamade.us/api/SOME-ENDPOINT
API Endpoints
| Endpoint documentation | What it does |
|---|---|
| /api/usaddress/ | Parse an address in the United States into tagged components |
| /api/bulk/usaddress/ | Bulk parse a list of addresses |
| /api/probablepeople/ | Parse a western name into tagged components |
| /api/bulk/probablepeople/ | Bulk parse a list of names |
| /api/usage/ | Get API usage statistics for an API key |
GET
/api/usaddress/
Parse an address in the United States into tagged components
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 parserator@datamade.us |
Response
Returns a JSON object with:
| Parameter | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
meta |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
type |
Identified address type.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||
result |
JSON object of parsed address parts (
|
Example
Let’s parse
123 main st, Chicago IL:
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"
}
]
}
POST
api/bulk/usaddress/
Bulk parse a list of addresses
usaddress can handle bulk parsing. It's limited to batches of 500 addresses at a time.
Request body
All fields are required in your request body.
| Parameter | Description |
|---|---|
object_list |
A list of addresses |
api_key |
Customer API key (GUID). To get a key, contact DataMade parserator@datamade.us |
Response
Returns a JSON object with:
| Parameter | Description | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
meta |
|
||||||||||||||||||||||||||||
result |
A JSON array of parsed addresses. Here is the full list of available tags.
|
Example
Let’s parse with python:
import requests
addresses = ['123 N West Avenue #1 Chicago, IL 60601',
'123 N West Avenue #2 Chicago, IL 60601',
'123 N West Avenue #3 Chicago, IL 60601']
url = 'https://parserator.datamade.us/api/bulk/usaddress/'
body = {
'api_key': '<YOUR API KEY>',
'object_list': addresses
}
response = requests.post(url, body=query)
Response:
{
"meta": {
"status": "ok",
"message": "",
"parser": "usaddress",
"input_object_list": [
"123 N West Avenue #1 Chicago, IL 60601",
"123 N West Avenue #2 Chicago, IL 60601",
"123 N West Avenue #3 Chicago, IL 60601"
],
"number_of_successful_parses": 3,
"number_of_failed_parses": 0,
"status_code": 200
},
"result": [
{
"result": [
{
"value": "123",
"tag": "AddressNumber"
},
{
"value": "N",
"tag": "StreetNamePreDirectional"
},
{
"value": "West",
"tag": "StreetName"
},
{
"value": "Avenue",
"tag": "StreetNamePostType"
},
{
"value": "# 1",
"tag": "OccupancyIdentifier"
},
{
"value": "Chicago",
"tag": "PlaceName"
},
{
"value": "IL",
"tag": "StateName"
},
{
"value": "60601",
"tag": "ZipCode"
}
],
"type": "Street Address",
"input_address": "123 N West Avenue #1 Chicago, IL 60601"
},
{
"result": [
{
"value": "123",
"tag": "AddressNumber"
},
{
"value": "N",
"tag": "StreetNamePreDirectional"
},
{
"value": "West",
"tag": "StreetName"
},
{
"value": "Avenue",
"tag": "StreetNamePostType"
},
{
"value": "# 2",
"tag": "OccupancyIdentifier"
},
{
"value": "Chicago",
"tag": "PlaceName"
},
{
"value": "IL",
"tag": "StateName"
},
{
"value": "60601",
"tag": "ZipCode"
}
],
"type": "Street Address",
"input_address": "123 N West Avenue #2 Chicago, IL 60601"
},
{
"result": [
{
"value": "123",
"tag": "AddressNumber"
},
{
"value": "N",
"tag": "StreetNamePreDirectional"
},
{
"value": "West",
"tag": "StreetName"
},
{
"value": "Avenue",
"tag": "StreetNamePostType"
},
{
"value": "# 3",
"tag": "OccupancyIdentifier"
},
{
"value": "Chicago",
"tag": "PlaceName"
},
{
"value": "IL",
"tag": "StateName"
},
{
"value": "60601",
"tag": "ZipCode"
}
],
"type": "Street Address",
"input_address": "123 N West Avenue #3 Chicago, IL 60601"
}
]
}
GET
/api/probablepeople/
Parse a western name into tagged components
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 marked with a red asterisk (*) are required.
| Parameter | Description |
|---|---|
name* |
Unstructured input name to parse |
type |
The type of entity to parse, one of Person or Corporation |
api_key* |
Customer API key (GUID). To get a key, contact DataMade parserator@datamade.us |
Response
Returns a JSON object with:
| Parameter | Description | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
meta |
|
||||||||||||||||||||||||
type |
Identified name type.
|
||||||||||||||||||||||||
result |
JSON object of parsed name parts (
|
Example
Let’s parse
Mr George 'Gob' Bluth II:
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"
}
]
}
If we wanted to specify that the string referred to a person, we could add the
type=Person parameter:
This would return the same response as above.
POST
api/bulk/probablepeople/
Bulk parse a list of names
probablepeople can handle bulk parsing. It's limited to batches of 500 names at a time.
Request body
All fields are required in your request body.
| Parameter | Description |
|---|---|
object_list |
A list of names |
api_key |
Customer API key (GUID). To get a key, contact DataMade parserator@datamade.us |
Response
Returns a JSON object with:
| Parameter | Description | ||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
meta |
|
||||||||||||||||||||||||||||
result |
A JSON array of parsed names. Here is the full list of available tags.
|
Example
Let’s parse with python:
import requests
domain = 'https://parserator.datamade.us/api/bulk/probablepeople/''
people = [
"Tobias Funke",
"Mr George 'Gob' Bluth II",
"Bluth's Original Frozen Banana"
]
body = {
'api_key': '<YOUR API KEY>',
'object_list': people
}
response = requests.post(domain, data=body)
Response:
{'meta': {'input_object_list': ['Tobias Funke',
"Mr George 'Gob' Bluth II",
"Bluth's Original Frozen Banana"],
'message': '',
'number_of_failed_parses': 0,
'number_of_successful_parses': 3,
'parser': 'probablepeople',
'status': 'ok',
'status_code': 200},
'result': [{'input_name': 'Tobias Funke',
'result': [{'tag': 'GivenName', 'value': 'Tobias'},
{'tag': 'Surname', 'value': 'Funke'}],
'type': 'Person'},
{'input_name': "Mr George 'Gob' Bluth II",
'result': [{'tag': 'PrefixMarital', 'value': 'Mr'},
{'tag': 'GivenName', 'value': 'George'},
{'tag': 'Nickname', 'value': "'Gob'"},
{'tag': 'Surname', 'value': 'Bluth'},
{'tag': 'SuffixGenerational', 'value': 'II'}],
'type': 'Person'},
{'input_name': "Bluth's Original Frozen Banana",
'result': [{'tag': 'Corporation',
'value': "Bluth's Original Frozen Banana"}],
'type': 'Corporation'}]}
GET
/api/usage/
Get API usage statistics for an API key
Query parameters
All query parameters are required.
| Parameter | Default value | Description |
|---|---|---|
api_key |
Required. Customer API key (GUID). To get a key, contact DataMade parserator@datamade.us | |
start_date |
30 days ago from the current date and time |
Optional. Start date for querying usage.
Expects a date either in UTC ISO 8601 format (example: 2015-04-12T18:51:19)
or YYYY-MM-DD (example: 2015-04-12).
|
end_date |
The current date and time |
Required. End date for querying usage.
Expects a date either in UTC ISO 8601 format (example: 2015-04-12T18:51:19)
or YYYY-MM-DD (example: 2015-04-12).
|
Response
Returns a JSON object with:
| Parameter | Description | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
meta |
|
||||||||||||||||||||||
api_calls_made |
Numer of API calls made between the two dates. |
Example
Let’s get usage statistics:
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 on the usaddress or parserator GitHub Issues pages. We will use your information to improve our models.
