Application Programming Interface

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

Resource URI

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

"https://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. https://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. https://gnrd.globalnames.org/name_finder.json?text=A+spider+named+Pardosa+moesta+Banks,+1892
engine (optional)
Type: integer, Default: 0. Heuristic and Bayes approaches is 0, skipping Bayes algorithm is 1.
e.g. https://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia&engine=1
unique (optional)
Type: boolean (true/false or 1/0), Default: true. If 'true', response has unique names without offsets.
e.g. https://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia&unique=true
verbatim (optional)
Type: boolean (true/false or 1/0), Default: false. If 'true', response includes verbatim strings.
e.g. https://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia&verbatim=false
detect_language (optional)
Type: boolean (true/false or 1/0), Default: false. When 'true', Bayes algorithm will use a training set for the detected language, if it is available. Only English and German are supported at the moment. If there is an unsupported language, English training set is used.
e.g. https://gnrd.globalnames.org/name_finder.json?url=http://es.wikipedia.org/wiki/Animalia&detect_language=true
callback (optional)
Type: string. Can be used for cross-domain JavaScript integration.
e.g. https://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia&callback=MyCoolCallBack

Optional parameters for verifying found names

with_verification (optional)
Type: bolean (true/false). Resolve found names against all available Data Sources and return the one best match. .
e.g. https://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia&with_verification=true If you are interested in results from particular data sources use the preferred_data_sources parameter
preferred_data_sources (optional)
Type: string. Pipe-separated list of data source ids. If there is a match for these data sources, the result will always be shown at the preferred_results section. See the list of Data Sources .
e.g. https://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Animalia&preferred_data_sources=1|12

Example

e.g. https://gnrd.globalnames.org/name_finder.json?url=http://en.wikipedia.org/wiki/Araneae&preferred_data_sources=1|12

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://localhost:9292/name_finder.json?token=6ofibu06av",
  "input_url": "https://en.wikipedia.org/wiki/Animalia",
  "file": null,
  "status": 303,
  "engines": [
    "gnfinder"
  ],
  "unique": false,
  "verbatim": true,
  "parameters": {
    "return_content": false,
    "with_verification": false,
    "preferred_data_sources": [
      1,
      12
    ],
    "detect_language": false,
    "engine": 0,
    "no_bayes": false
  },
  "queue_size": 1
}

Final Response After Having Polled Token URL

      {
        "token_url": "http://localhost:9292/name_finder.json?token=6ofibu06av",
        "input_url": "https://en.wikipedia.org/wiki/Animalia",
        "file": null,
        "status": 200,
        "engines": [
          "gnfinder"
        ],
        "unique": false,
        "verbatim": true,
        "parameters": {
          "return_content": false,
          "with_verification": false,
          "preferred_data_sources": [
            1,
            12
          ],
          "preferred_data_sources": [],
          "detect_language": false,
          "engine": 0,
          "no_bayes": false
        },
        "names": [
          {
     with_verification": "Animalia)",
            "scientificName": "Animalia",
            "offsetStart": 4207,
            "offsetEnd": 4216
          }, ...
          {
            "verbatim": "Sunda",
            "scientificName": "Sunda",
            "offsetStart": 85264,
            "offsetEnd": 85269
          }
        ],
        "language_used": "eng",
        "execution_time": {
          "text_preparation_duration": 3.831543207168579,
          "find_names_duration": 1.442460060119629,
          "total_duration": 5.2784082889556885
        },
        "verified_names": [
          {
            "supplied_name_string": "Animalia",
            "is_known_name": true,
            "results": {
              "match_value": "EXACT",
              "name_string": "Animalia",
              "current_name_string": "Animalia",
              "data_source_id": 1,
              "data_source_title": "Catalogue of Life",
              "classification_path": "Animalia",
              "edit_distance": 0
            },
            "preferred_results": [
              {
                "data_source_id": 1,
                "data_source_title": "Catalogue of Life",
                "name": "Animalia",
                "taxon_id": "54767744"
              }
            ]
          }, ...
          {
            "supplied_name_string": "Runa",
            "is_known_name": true,
            "results": {
              "match_value": "EXACT",
              "name_string": "Runa L. Agassiz, 1841",
              "current_name_string": "Runa L. Agassiz, 1841",
              "data_source_id": 9,
              "data_source_title": "World Register of Marine Species",
              "classification_path": "Biota|Animalia|Echinodermata|Echinozoa|Echinoidea|Euechinoidea|Irregularia|Neognathostomata|Clypeasteroida|Scutellina||Runa",
              "edit_distance": 0
            },
            "preferred_results": [
              {
                "data_source_id": 12,
                "data_source_title": "Encyclopedia of Life",
                "name": "Runa",
                "taxon_id": "24228379"
              }
            ]
          },
          {
            "supplied_name_string": "Sunda",
            "is_known_name": true,
            "results": {
              "match_value": "EXACT",
              "name_string": "Sunda Pruthi, 1936",
              "current_name_string": "Stirellus Osborn & Ball, 1902",
              "data_source_id": 181,
              "data_source_title": "The Interim Register of Marine and Nonmarine Genera",
              "classification_path": "Biota|Animalia|Arthropoda|Hexapoda|Insecta|Hemiptera|Cicadellidae|Stirellus",
              "edit_distance": 0
            },
            "preferred_results": []
          }
        ],
        "total": 450,
        "queue_size": 0
      }

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('https://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