The v2.parse.name API consists of two API actions, GET /api/v2/names/parse and POST /api/v2/names/parse_file

API Signatures

• APIs routes are versioned starting with /api/v2/
• APIs return only JSON
• US-English language is currently only supported (en-US locale), and is the default. Additional languages might be supported in the future, and will be configurable through the locale query param.

Authenticating with the parser

You must have a verified account in order to make requests against the JSON API. Reach out to Brian Long (Twitter: @brianlong & Telephone: 303-443-2070) in order to get your account verified.

Pass your API token in as the Authorization header, like in this curl example:

$ curl -H "Authorization: secret-api-token" https://v2.parse.name/api/v2/names/parse?q=John%20Doe

Examples in this API guide are demonstrated using curl, but you should use an HTTP library of your choice. Curl examples also omit the Authorization header for simplicity.

Parse Name API

200 responses will indicate success. 400 responses indicate that we couldn't parse the input.

Parse a single name, John Doe

$ curl https://v2.parse.name/api/v2/names/parse?q=John%20Doe

Response:

{
  "base": {
    "input": "John Doe",
    "locale": "en-US"
  },
  "name": [
    {
      "given_name": "John",
      "surname": "Doe",
      "input_placement_scores": {
        "[\"given_name\", \"surname\"]": 1.943,
        "[\"surname\", \"given_name\"]": 0.057,
        "max_candidate": ["given_name", "surname"]
      },
      "full_name": "John Doe"
    }
  ]
}

An input_placement_scores key will be returned for name inputs that have two and three components. This means inputs that are either a first and last name, or first, middle, and last name. These represent a score for how probable the input is in a given structure.

Take for instance the input "Doe John", a common pattern where the last name appears first. To decipher this, we score how probable the input is either "first last", or "last first", and return whichever is most probable. For clarity, these scores are returned.

For name inputs that have more than three components, other means are used to determine word placement.

Parse two names, Brian and Jennifer Long

$ curl https://v2.parse.name/api/v2/names/parse?q=Brian%20and%20Jennifer%20Long

Response:

{
  "base": {
    "input": "Brian and Jennifer Long",
    "locale":"en-US"
  },
  "name": [
    {
      "given_name": "Brian",
      "surname": "Long",
      "input_placement_scores": {
        "[\"given_name\", \"surname\"]": 1.948,
        "[\"surname\", \"given_name\"]": 0.052,
        "max_candidate": ["given_name", "surname"]
      },
      "full_name": "Brian Long"
    },
    {
      "given_name": "Jennifer",
      "surname": "Long",
      "input_placement_scores": {
        "[\"given_name\", \"surname\"]": 1.948,
        "[\"surname\", \"given_name\"]": 0.052,
        "max_candidate": ["given_name", "surname"]
      },
      "full_name": "Jennifer Long"
    }
  ]
}

Parse an organization, First Movers Advantage

$ curl https://v2.parse.name/api/v2/names/parse?q=First%20Movers%20Advantage

Response:

{
  "base": {
    "input": "First Movers Advantage",
    "locale": "en-US"
  },
  "organization": [
    {
      "name": "First Movers Advantage"
    }
  ]
}

Parse a name and an organization

John Doe, First Movers Advantage

$ curl https://v2.parse.name/api/v2/names/parse?q=John%20Doe,%20First%20Movers%20Advantage

Response:

{
  "base": {
    "input": "John Doe, First Movers Advantage",
    "locale": "en-US"
  },
  "name": [
    {
      "given_name": "John",
      "surname": "Doe",
      "input_placement_scores": {
        "[\"given_name\", \"surname\"]": 1.943,
        "[\"surname\", \"given_name\"]": 0.057,
        "max_candidate": ["given_name","surname"]
      },
      "full_name": "John Doe"
    }
  ],
  "organization": [
    {
      "name": "First Movers Advantage"
    }
  ]
}

Ancillary Data

Name inputs are dissected into many parts. Take for instance a complex input like Mr. Richard Antle III (Rich) - President, CRE, CRS, e-PRO, REALTOR®, SRES which we would respond with:

{
  "base": {
    "input": "Mr. Richard Antle III (Rich) - President, CRE, CRS, e-PRO, REALTOR®, SRES",
    "locale": "en-US"
  },
  "name": [
    {
      "salutation": ["Mr"],
      "alternate_name": ["Rich"],
      "given_name": "Richard",
      "surname": "Antle",
      "credential": ["CRE", "CRS", "e-Pro", "Realtor", "SRES"],
      "job_title": ["President"],
      "suffix": ["III"],
      "input_placement_scores": {
        "[\"given_name\", \"surname\"]": 1.979,
        "[\"surname\", \"given_name\"]": 0.021,
        "max_candidate": ["given_name", "surname"]
      },
      "full_name": "Richard Antle"
    }
  ]
}

This name has many parts to it, including a salutation, alternate name, credentials, a job title, and a suffix. We call these things "ancillary data" of the name. The following is a full list of ancillary data that a name can have, and keys returned for:

• alternate_name
• credential
• job_title
• prefix
• salutation
• suffix

Error Responses

Attempting to parse a name which failed

John

$ curl https://v2.parse.name/api/v2/names/parse?q=John

Response:

{
  "base": {
    "input": "John",
    "locale": "en-US",
    "errors": {
      "input": [
        "could not be distinguished between a name or organization"
      ]
    }
  }
}

tyler a b c d e f g h i j k l m n o p

$ curl https://v2.parse.name/api/v2/names/parse?q=tyler%20a%20b%20c%20d%20e%20f%20g%20h%20i%20j%20k%20l%20m%20n%20o%20p

Response:

{
  "base": {
    "input": "tyler a b c d e f g h i j k l m n o p",
    "locale": "en-US",
    "errors": {
      "input": [
        "is suspiciously long"
      ]
    }
  }
}

Parse an uploaded CSV file

Instead of making API requests for each input you would like to parse, you can upload a CSV file containing inputs and do a batch parse. We'll then parse the file and email you the results as a CSV file when complete.

In the payload, you'll need to specify two things:

• the file to upload, specified by unparsed_file
• the column name that contains the input to put through the parser, input_column_name

$ curl -X POST \
  https://v2.parse.name/api/v2/names/parse_file \
  -H 'Authorization: my-api-token' \
  -H 'Content-Type: multipart/form-data' \
  -F unparsed_file=@/Users/my-user/path-to-csv-file/parse_file.csv \
  -F "input_column_name=my input column name"

Response:

{
  "message": "Your input file is being processed and will be available soon. We will send a link to the following email: my-email@example.com"
}

The CSV file you upload can have any format that is a valid CSV, but you will need to tell us which column name contains the inputs that should go into the parser. Then, for each row we will then append the parsed result to the right of the last column. For example in this simple CSV file, we would input my input column name as the input_column_name param.

 

my input column name
Tyler VanNurden
First Movers Advantage

   

The (abbreviated) parsed file then emailed to you will be:

my input column name	name0_given_name	name0_secondary_name	name0_surname
Tyler VanNurden	Tyler		Vannurden
First Movers Advantage

 

For this CSV file, we would use input as the input_column_name param.

id	my input column name	foo	random
1	Tyler VanNurden	bar
2	First Movers Advantage	baz
3		foo

   

The (abbreviated) parsed file then emailed to you will be:

id	my input column name	foo	random	name0_given_name	name0_secondary_name	name0_surname
1	Tyler VanNurden	bar		Tyler		Vannurden
2	First Movers Advantage	baz
3		foo

 

Full examples of these results can be viewed at

https://v2.parse.name/parsed_csv_file1.csv

https://v2.parse.name/parsed_csv_file2.csv