Phylotastic/TNRS/Comments

From Evoio
Jump to: navigation, search

Contents

Core API

GET | POST /submit

Submit a list of taxonomic names to be resolved.

URI

http://api.phylotastic.org/tnrs/submit

Parameters

  • query (required, string): A URL-encoded, newline-delimited list of taxon name (e.g. Panthera+tigris%0AEutamias+minimus%0AMagnifera+indica%0AHumbert+humbert)

Returns

Field Meaning Examples
message Human readable message "Your request is being processed. You can retrieve the results at http://api.phylotastic.org/tnrs/retrieve/76ca0e9a3ab78e6bc5b4e362c8c40e15."
submit date Date and time at which the request was submitted "Mon Jun 11 20:25:16 2012"
token Unique identifier assigned to the request (jobId) "76ca0e9a3ab78e6bc5b4e362c8c40e15"
uri Address at which the results can be retrieved "http://api.phylotastic.org/tnrs/retrieve/76ca0e9a3ab78e6bc5b4e362c8c40e15"

Example

GET http://api.phylotastic.org/tnrs/submit?query=Panthera+tigris%0AEutamias+minimus%0AMagnifera+indica%0AHumbert+humbert


{
   "message": "Your request is being processed. You can retrieve the results at http://api.phylotastic.org/tnrs/retrieve/76ca0e9a3ab78e6bc5b4e362c8c40e15.", 
   "submit date": "Mon Jun 11 20:25:16 2012", 
   "token": "76ca0e9a3ab78e6bc5b4e362c8c40e15", 
   "uri": "http://api.phylotastic.org/tnrs/retrieve/76ca0e9a3ab78e6bc5b4e362c8c40e15"
}


GET /retrieve

Retrieve the resolved names

URI

http://api.phylotastic.org/tnrs/retrieve/<token>

Parameters

  • none

Returns

Section Field Meaning Examples
metadata jobId The job-id which was submitted (for asynchronous requests) "76ca0e9a3ab78e6bc5b4e362c8c40e15"
metadata submitDate Date on which this job was submitted. "Mon Jun 11 20:25:16 2012"
metadata sources An array of all the sources available to our TNRS service, in the following format:
Field Description Example
sourceId A short string used to name this source "ITIS", "NCBI Taxonomy", "iPlant TNRS"
sourceName The full name of this source "iPlant Collaborative TNRS v3"
uri A URL used to identify this source; generally the HTTP URL for the frontpage "http://www.itis.gov/", "http://www.ncbi.nlm.nih.gov/taxonomy"
rank The rank to which we assign this source. Multiple sources *cannot* have the same rank. 1, 4, 5
status The status of this TNRS at the time of this request. Note that "offline" or "temporarily offline" TNRSes were NOT queried for the results returned in this document. Either "online" or "offline" or "temporarily offline"
annotations A dictionary containing a list of annotations which MIGHT be produced by this TNRS, mapped to descriptions of that annotation. {'nucleotide_uri': "A link to nucleotide sequences on GenBank for this taxon", 'protein_uri': "A link to protein sequences on GenBank for this taxon."}
names submittedName The name that was submitted for name resolution. "Feeelis tigris"
names matchCount The number of successful matches 0, 2, 4
names matches An array containing a list of matches, in the following format:
Field Description Example
sourceId A short string used to name the TNRS source from which this name was extracted. See metadata['sources'] to look up the metadata associated with this source. "ITIS", "NCBI Taxonomy", "iPlant TNRS"
matchedName The name matched in this TNRS from the name submitted. There MUST be a name entry in the TNRS for this name, although it is not necessarily valid/accepted. Unlike DarwinCore's scientificName field, we prefer that this not contain the taxonomic authority, although it may contain it if the TNRS does not provide a single uni/bi/trinomial. "Felis tigris"
acceptedName The currently accepted name for individuals of the taxon identified in matchedName. If the TNRS does not contain synonymy information, or If there is no currently accepted name, this field should be blank. Unlike DarwinCore's acceptedNameUsage field, we prefer that this not contain the taxonomic authority, although it may contain it if the TNRS does not provide a single uni/bi/trinomial. "Panthera tigris"
uri A URI corresponding to the acceptedName (NOT the matchedName). Ideally, this should be an HTTP URL to an RDF document, but an HTML document is also fine. TODO: We need a way of indicating whether this is an RDF document or not; either with different field names ("uri" vs "rdf") or possibly hacking it via different schemas: "http+rdf://" vs "http://", for instance. "http://www.ubio.org/authority/metadata.php?lsid=urn:lsid:ubio.org:namebank:2478188" (RDF) or "http://www.itis.gov/servlet/SingleRpt/SingleRpt?search_topic=TSN&search_value=183805" (HTML)
annotations A dictionary of annotations specific to this TNRS. See metadata['source'][0]['annotations'], etc. for the descriptions of these annotations. {'nucleotide_uri': "http://www.ncbi.nlm.nih.gov/nuccore/?term=txid9694[Organism:exp]", 'protein_uri': "http://www.ncbi.nlm.nih.gov/protein/?term=txid9694[Organism:exp]"}
score A score (from 0 to 1) indicating how certain the TNRS is of this match. Note that in some cases (where the TNRS does not provide scores), the controller may calculate its own score (either by calculating the number of characters different between the matchedName and the submittedName, or by simply setting it to '1.0' where they are identical and '0.5' where they are not. 0.5, 0.6667, 0.98989

Extensions TNRastic v. 1.2.0

Parameters in bold are required.

POST /submit

Submit a file of taxonomic names to be resolved.

Parameters

  • file: A newline formatted list of taxonomic names

Returns

Identical to GET /submit with query parameter.

GET /sources/list

Obtain a ranked list the ids of all available sources.

Parameters

  • none

Returns

A JSON object containing the list of source_id. Example: http://sharp.iplantcollaborative.org/sources/list

GET /sources/<source_id>

Obtain the details about a particular source. If source_id is omitted, the details are returned for all available sources.

Parameters

  • <source_id>: the source id.
  • none to return the details for all sources.

Returns

A JSON object containing source(s) details. Example: http://sharp.iplantcollaborative.org/sources/NCBI

GET | POST | DELETE /delete/<token>

Cancels a running job

Parameters

  • <token>: the token returned by the /submit request.

Returns

A JSON object indicating success or an error message. Example: http://sharp.iplantcollaborative.org/delete/b6356e63f0c39d58066c1e772e24ff6f

browse site