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
- 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
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