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

http://resolver.globalnames.org/data_sources.xml (XML output)

http://resolver.globalnames.org/data_sources.json (JSON output)

Ruby Code Example

#!/usr/bin/env ruby
require 'rest-client'
puts RestClient.get("http://resolver.globalnames.org/data_sources.json")


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

http://resolver.globalnames.org/name_resolvers.xml (XML output)

http://resolver.globalnames.org/name_resolvers.json (JSON output)

Parameters (GET or POST)

names
Type: string, Default: none. List of names delimited by either pipe "|" or tab "\t". Use a pipe for GET requests
data
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.
best_match_only
Type: boolean (true/false), Default: 'false'. Returns just one result with the highest score.
preferred_data_sources
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": "http://resolver.globalnames.org/name_resolvers/31FqejHuQYm980nCtUgvaw.json",
  "data_sources": [ ],
  "status": "working",
  "message": "In the queue",
}

Final Output Example

{
  "id": "31FqejHuQYm980nCtUgvaw",
  "url": "http://resolver.globalnames.org/name_resolvers/31FqejHuQYm980nCtUgvaw.json",
  "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

id
Resolver request id. Your request is stored temporarily in the database and is assigned an id.
url
Using the url you can access your results for 7 days.
data_sources
A list of data source ids you used for name resolution. If no data sources were given the list is empty.
context
Appears if 'with_context' parameter is set to true.
context_data_source_id
The id of a data source used to create the context.
context_clade
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.
data
A container for the resolution data.
supplied_name_string
The name string in the query.
is_known_name
True if name was found by exact match, or by matching the name's canonical form (without authors etc). False otherwise.
supplied_id
The id of the name string in the query (if provided).
results
A container for displaying results for a particular name string.
data_source_id
The id of the data source where a name was found.
gni_uuid
An identifier for the found name string used in Global Names.
name_string
The name string found in this data source.
canonical_form
A "canonical" version of the name generated by the Global Names parser
classification_path
Tree path to the root if a name string was found within a data source classification.
classification_path_ids
Same tree path using taxon_ids (see below)
taxon_id
An identifier supplied in the source Darwin Core Archive for the name string record
local_id
Shows id local to the data source (if provided by the data source manager)
match_type
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
prescore
Displays points used to calculate the score delimited by '|' -- "Match points|Author match points|Context points". Negative points decrease the final result.
score
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
status
The final status of the request -- 'success' or 'failure'
status_message
Message associated with the status

Examples

http://resolver.globalnames.org/name_resolvers.xml?names=Plantago+major|Monohamus+galloprovincialis|Felis+concolor&data_source_ids=1|12
http://resolver.globalnames.org/name_resolvers.json?names=Plantago+major|Monohamus+galloprovincialis|Felis+concolor+species
http://resolver.globalnames.org/name_resolvers.json?names=Plantago+major|Monohamus+galloprovincialis|Felis+concolor&data_source_ids=1|12&resolve_once=false

Ruby Code Example

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

puts "GET request\n"
puts RestClient.get(URI.escape("http://resolver.globalnames.org/name_resolvers.json?names=Plantago 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 RestClient.post(resource_url, :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 RestClient.post(resource_url, :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 RestClient.post(http://resolver.globalnames.org/name_resolvers, :format => "json", :file =>File.new("names_list.txt", "r:utf-8"), :resolve_once => false, :data_source_ids => "1")
end