API
The simplest way to connect to our database is via HTTP Basic authentication. Use your authentication token and a GET request to http://parse.name/names/parse.xml with 'q' parameter in the URL (remember to URI escape your request string. Especially embedded '&' which should be '%26'). For example:
<![CDATA[
curl -u 'YOUR_AUTHENTICATION_TOKEN:X' http://localhost:3000/names/parse.xml?q=john%20doe,%20president
]]>
will provide an XML response similar to:
<![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<name>
<id type="integer">2</id>
<input>john doe, president</input>
<parse_status>success</parse_status>
<parse_method>robot</parse_method>
<language>en</language>
<created_on type="date">2010-08-17</created_on>
<organizations type="array">
</organizations>
<people type="array">
<person>
<salutation></salutation>
<prefix></prefix>
<given_name>John</given_name>
<secondary_name></secondary_name>
<matrynomic_surname></matrynomic_surname>
<patrynomic_surname>Doe</patrynomic_surname>
<suffix></suffix>
<alternate_name></alternate_name>
<credentials></credentials>
<gender></gender>
<is_deceased type="boolean">false</is_deceased>
</person>
</people>
<job_titles type="array">
<job_title>
<title>President</title>
</job_title>
</job_titles>
</name>
]]>
Here is the full XML structure with all elements expanded:
<![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<name>
<id type="integer">2</id>
<input>john doe, president</input>
<parse_status>success</parse_status>
<parse_method>robot</parse_method>
<language>en</language>
<created_on type="date">2010-08-17</created_on>
<organizations type="array">
<organization>
<name>First Movers Advantage, LLC</name>
<is_dba type="boolean"></is_dba>
</organization>
</organizations>
<people type="array">
<person>
<salutation></salutation>
<prefix></prefix>
<given_name>John</given_name>
<secondary_name></secondary_name>
<matrynomic_surname></matrynomic_surname>
<patrynomic_surname>Doe</patrynomic_surname>
<suffix></suffix>
<alternate_name></alternate_name>
<credentials></credentials>
<gender></gender>
<is_deceased type="boolean">false</is_deceased>
</person>
</people>
<job_titles type="array">
<job_title>
<title>President</title>
</job_title>
</job_titles>
</name>
]]>
We also have a REST interface available. Here is a sample Ruby on Rails ActiveResource Client:
<![CDATA[
class ParseName < ActiveResource::Base
self.site = "http://#{PARSE_NAME_AUTHENTICATION_TOKEN}:X@parse.name/"
self.element_name = 'name'
def self.parse(s)
new(get(:parse, :q => s))
end
end
]]>
and sample use:
<![CDATA[
p = ParseName.parse('john doe')
p.parse_status # => "success"
p.people # => an array of Person(s)
p.people[0].given_name # => "John"
p.people[0].patrynomic_surname # => "Doe"
f = ParseName.parse('first movers advantage, llc')
f.parse_status # => "success"
f.organizations # => an array of Organization(s)
f.organizations[0].name # => "First Movers Advantage, LLC"
j = ParseName.parse('jane doe, president')
j.parse_status # => "success"
j.people[0].given_name # => "Jane"
j.people[0].patrynomic_surname # => "Doe"
j.job_titles # => an array of JobTitle(s)
j.job_titles[0].title # => "President"
]]>
NEW! Street Addresses:
We also have a REST interface available for parsing street addresses. Here is a sample Ruby on Rails ActiveResource Client:
<![CDATA[
class ParseStreetAddress < ActiveResource::Base
self.site = "http://#{PARSE_NAME_AUTHENTICATION_TOKEN}:X@parse.name/"
self.element_name = 'street_address'
def self.parse(s)
new(get(:parse, :q => s))
end
end
]]>
and sample use:
<![CDATA[
s = ParseStreetAddress.parse('1373 forest park cir ste 203, lafayette, co 80026-3193')
s.parse_status # => "success"
s.street_address # => "1373 Forest Park Cir Ste 203"
s.city # => "Lafayette"
s.state # => "CO"
s.postal_code # => "80026-3193"
]]>