Application Programming Interface (Alpha -- subject to change)

Ruby examples require the rest-client gem. To install it use:

gem install rest-client

Data Sources

You can resolve names against specific data sources or against the entire resolver database. To resolve against data sources you must supply their ids; this simple API allows you to find them.

Resource URI (XML output) (JSON output)

Ruby Code Example

#!/usr/bin/env ruby
require 'rest-client'
puts RestClient.get("")

Resolve Names

Receives a list of names and resolves each against the entire resolver database or against specific data sources. Underlying resolving and scoring algorithms are described elsewhere.

Resource URI (XML output) (JSON output)

Parameters (GET or POST)

Type: string, Default: none. List of names delimited by either pipe "|" or tab "\t". Use a pipe for GET requests
Type: string, Default: none. List of names delimited by new lines "\n". new lines. You may optionally supply your local id for each name as:
123|Parus major
125|Parus thruppi
126|Parus carpi
Names in the response will contain your supplied ids, facilitating integration. You can also upload files using a multipart POST request (see example below) with names and ids organized as in the example above.
data_source_ids (optional)
Type: string, Default: none. A pipe-delimited list of data sources. See a the list of data sources.
resolve_once (optional)
Type: boolean (true/false), Default: 'false'. Find the first available match instead of matches across all data sources with all possible renderings of a name. When 'true', response is rapid but incomplete.
Type: boolean (true/false), Default: 'false'. Returns just one result with the highest score.
Type: string, Default: none. A pipe-delimited list of data sources (see data_source_ids parameter).
Creates a new section in results -- 'preferred_results' in addtion to 'results'. Preferred results contain only data received from requested data sources. When used togther with 'best_match_only' returnes only one highest scored result per a preffered data source. The resolution is still performed according to 'data_source_id' parameter.
with_context (optional)
Type: boolean (true/false), Default: 'true'. Reduce the likelihood of matches to taxonomic homonyms. When 'true' a common taxonomic context is calculated for all supplied names from matches in data sources that have classification tree paths. Names out of determined context are penalized during score calculation.
with_vernaculars (optional)
Type: boolean (true/false), Default: 'false'. Return 'vernacular' field to present common names provided by a data source for a particular match.
with_canonical_ranks (optional)
Type: boolean (true/false), Default: 'false'. Returns 'canonical_form' with infraspecific ranks, if they are present.

Initial Output Example

The API operates in a queue with an initial response containing a url to be polled for a final response. For a query containing fewer than 1000 names, the queue is not used.


  "id": "31FqejHuQYm980nCtUgvaw",
  "url": "",
  "data_sources": [ ],
  "status": "working",
  "message": "In the queue",

Final Output Example

  "id": "31FqejHuQYm980nCtUgvaw",
  "url": "",
  "data_sources": [ ],
  "context": [
      "data_source_id": "1",
      "clade": Spermatophyta
  "parameters": {
    "with_context": true,
    "data_sources": [ ],
    "resolve_once": true
  "data": [
      "supplied_name_string": "Plantago major",
      "is_known_name": true,
      "supplied_id": "1",
      "results": [
          "data_source_id": 4,
          "gni_uuid": "09880732-5417-5512-2952-230616235585",
          "name_string": "Plantago major",
          "canonical_form": "Plantago major",
          "classification_path": "|Eukaryota|Viridiplantae|Streptophyta|Streptophytina|Embryophyta|Tracheophyta|Euphyllophyta|Spermatophyta|Magnoliophyta|||||Lamiales|Plantaginaceae|Plantagineae|Plantago|Plantago major",
          "classification_path_ids": "131567|2759|33090|35493|131221|3193|58023|78536|58024|3398|71240|91827|71274|91888|4143|156152|216794|26867|29818",
          "taxon_id": "29818",
          "local_id": null,
          "match_type": 1,
          "prescore": "3|0|0",
          "score": 0.9882161311296586
  "status": "success",
  "message": "Success",

Output Fields

Resolver request id. Your request is stored temporarily in the database and is assigned an id.
Using the url you can access your results for 7 days.
A list of data source ids you used for name resolution. If no data sources were given the list is empty.
Appears if 'with_context' parameter is set to true.
The id of a data source used to create the context.
A lowest taxonomic level in the data source that contains 90% or more of all names found. If there are too few names to determine, this element remains empty.
A container for the resolution data.
The name string in the query.
True if name was found by exact match, or by matching the name's canonical form (without authors etc). False otherwise.
The id of the name string in the query (if provided).
A container for displaying results for a particular name string.
The id of the data source where a name was found.
An identifier for the found name string used in Global Names.
The name string found in this data source.
A "canonical" version of the name generated by the Global Names parser
Tree path to the root if a name string was found within a data source classification.
Same tree path using taxon_ids (see below)
An identifier supplied in the source Darwin Core Archive for the name string record
Shows id local to the data source (if provided by the data source manager)
Explains how resolver found the name. If the resolver cannot find names corresponding to the entire queried name string, it sequentially removes terminal portions of the name string until a match is found.
  • 1 - Exact match
  • 2 - Exact match by canonical form of a name
  • 3 - Fuzzy match by canonical form
  • 4 - Partial exact match by species part of canonical form
  • 5 - Partial fuzzy match by species part of canonical form
  • 6 - Exact match by genus part of a canonical form
Displays points used to calculate the score delimited by '|' -- "Match points|Author match points|Context points". Negative points decrease the final result.
A confidence score calculated for the match. 0.5 means an uncertain result that will require investigation. Results higher than 0.9 correspond to 'good' matches. Results between 0.5 and 0.9 should be taken with caution. Results less than 0.5 are likely poor matches. The scoring is described in more details on the About page
The final status of the request -- 'success' or 'failure'
Message associated with the status


Ruby Code Example

#!/usr/bin/env ruby
require 'rest-client'
require 'uri'

puts "GET request\n"
puts RestClient.get(URI.escape(" major|Monohamus galloprovincialis|Felis concolor&resolve_once=false&data_source_ids=1|3"))

puts "\n\nPOST request with names and supplied IDs using 'names' parameter' \n"
puts, :format => "json", :names =>"Plantago major|Pardosa moesta L.|Felis concolor", :resolve_once => false, :data_source_ids => "1")

puts "\n\nPOST request with names and supplied IDs using 'data' parameter' \n"
puts, :format => "json", :data =>"1|Plantago major\n2|Pardosa moesta L.\n3|Felis concolor", :resolve_once => false, :data_source_ids => "1")

if File.exists?('names_list.txt')
    puts "\n\nPOST request with an uploaded file\n"
    puts, :format => "json", :file =>"names_list.txt", "r:utf-8"), :resolve_once => false, :data_source_ids => "1")