Application Programming Interface

This API produces an immediate response containing a token URL to be polled. See the example below.

Resource URI

"http://gnrd.globalnames.org/name_finder.json (JSON output)"

"http://gnrd.globalnames.org/name_finder.xml (XML output)"

Parameters (GET or POST)

url
Type: string. An encoded URL for a web page, PDF, Microsoft Office document, or image file
e.g. http://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia
file
When using multipart/form-data as the content-type, a file may be sent.
text
Type: string. Text content; best used with a POST request
e.g. http://gnrd.globalnames.org/name_finder.json?text=A+spider+named+Pardosa+moesta+Banks,+1892
engine (optional)
Type: integer, Default: 0. Either 1 for TaxonFinder, 2 for NetiNeti, or 0 for both. If absent, both engines are used.
e.g. http://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia&engine=1
unique (optional)
Type: boolean (true/false), Default: true. If 'true', response has unique names without offsets.
e.g. http://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia&unique=true
verbatim (optional)
Type: boolean (true/false), Default: false. If 'true', response excludes verbatim strings.
e.g. http://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia&verbatim=false
detect_language (optional)
Type: boolean (true/false), Default: true. When 'true', NetiNeti is not used if the language of incoming text is determined not to be English. When 'false', NetiNeti will be used if requested.
e.g. http://gnrd.globalnames.org/name_finder.json?url=http://es.wikipedia.org/wiki/Animalia&detect_language=false
callback (optional)
Type: string. Can be used for cross-domain JavaScript integration.
e.g. http://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia&callback=MyCoolCallBack

Optional resolution parameters

all_data_sources (optional)
Type: bolean (true/false). Resolve found names against all available Data Sources .
e.g. http://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia&all_data_sources=true
data_source_ids (optional)
Type: string. Pipe separated list of data source ids to resolve found names against. See list of Data Sources .
e.g. http://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia&data_source_ids=1|169

Example

e.g. http://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Araneae

Initial Response Containing Token URL

An HTTP status code of 303 "See Other" will be sent and the Location will be the token URL.

{
                "token_url" : "http://gnrd.globalnames.org/name_finder.json?token=VmuYurv3QLyMXLABnqU1vg",
                "input_url" : "http://en.wikipedia.org/wiki/Araneae",
                "file"      : "",
                "status"    : 303,
                "engines"   : ["TaxonFinder", "NetiNeti"],
                "unique"    : false,
                "verbatim"  : true,
                "queue_size": 1
              }

Final Response After Having Polled Token URL

{
                "token_url" : "http://gnrd.globalnames.org/name_finder.json?token=VmuYurv3QLyMXLABnqU1vg",
                "input_url" : "http://en.wikipedia.org/wiki/Araneae",
                "file"      : "",
                "status"    : 200,
                "engines"   : ["TaxonFinder", "NetiNeti"],
                "unique"    : false,
                "verbatim"  : true,
                "agent"     : {
                  "code"         : "200",
                  "content_type" : "text/html; charset=UTF-8",
                  "filename"     : "Araneae.html"
                },
                "created"   : "2012-06-28T03:21:28-04:00",
                "execution_time" : {
                  "find_names_duration" : 1.935246,
                  "total_duration"      : 4.051854
                },
                "total"    : 347,
                "names":[
                  {
                    "verbatim"       : "T. nigroannulatum build",
                    "identifiedName" : "T. nigroannulatum",
                    "scientificName" : "Theridion nigroannulatum",
                    "offsetStart"    : 39686,
                    "offsetEnd"      : 39708,
                  },
                  {
                    "verbatim"       : "Uloboridae",
                    "identifiedName" : "Uloboridae"
                    "scientificName" : "Uloboridae",
                    "offsetStart"    : 39885,
                    "offsetEnd"      : 39896,
                  },
                  ...etc...
                ]
              }

Advanced

If you have many large documents to send or experience long network delays, you can gzip compress your POST body and set the request header, Content-Encoding : gzip.

Example ruby script

require 'active_support/all'
              require 'addressable/uri'
              
              addressable = Addressable::URI.new
              addressable.query_values = { :text => really_big_text }
              gz_payload = ActiveSupport::Gzip.compress(addressable.query)
              
              uri = URI('http://gnrd.globalnames.org/name_finder.json')
              req = Net::HTTP::Post.new(uri.path)
              req["Content-Encoding"] = "gzip"
              req["Content-Length"] = gz_payload.size
              req["X-Uncompressed-Length"] = addressable.query.size
              req.body = gz_payload
              
              res = Net::HTTP.start(uri.hostname, uri.port) do |http|
                http.request(req)
              end