OJ Break API Reference
Introduction
OJ_Break is the name of the OSUC biodiversity RESTful(-like) API service. The API responds exclusively in JavaScript Object Notation (JSON) and accepts only HTTP GET and POST requests indiscriminately unlike a true REST API. Built using Oracle's PL/SQL database language, the API is fast but often inflexible and inconsistent, so take note of all of the comments below.
Contents
- 1 Overview
- 2 Reference
- 2.1 Procedures
- 2.2 Data Type Glossary
- 2.2.1 Classes
- 2.2.1.1 taxon_basic
- 2.2.1.2 taxon_hierarchy
- 2.2.1.2.1 Kingdom
- 2.2.1.2.2 Phylum
- 2.2.1.2.3 Subphylum
- 2.2.1.2.4 Class
- 2.2.1.2.5 Subclass
- 2.2.1.2.6 Infraclass
- 2.2.1.2.7 Order
- 2.2.1.2.8 Suborder
- 2.2.1.2.9 Infraorder
- 2.2.1.2.10 Superfamily
- 2.2.1.2.11 Family
- 2.2.1.2.12 Subfamily
- 2.2.1.2.13 Tribe
- 2.2.1.2.14 Genus
- 2.2.1.2.15 Species
- 2.2.1.2.16 Subspecies
- 2.2.1.3 taxon_hier_unit
- 2.2.1.4 taxon_source
- 2.2.1.5 taxon_stats
- 2.2.2 Elements
- 2.2.1 Classes
Overview
All API requests must be formatted by first selecting the OJ_Break library then specifying the API method. Also, each method must include a callback argument even if a callback function is unnecessary (e.g. jQuery AJAX requests).
The format for API calls is: http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.[method]?[argument1]=[value1]&...
- Example: http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonInfo?tnuid=5012&callback=test
- Response: test({"taxon":"Oxyscelio consobrinus","author":"(Kieffer)","status":"Subsequent name/combination","rank":"Species","valid":"Valid","fossil":"N","rel_type":"Member",...
Reference
Procedures
Taxon
getTaxonStats
Description
Get some basic taxonomic statistics for a taxon from a tnuid.
Parameters
- tnuid: number
- callback: string
Return
- taxon: string
- author: string
- stats: taxon_stats
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonStats?tnuid=30148&callback=api
getTaxonInfo
Description
Get some basic taxonomic information for a taxon from a tnuid.
Parameters
- tnuid: number
- inst_id: number
- callback: string
Return
- taxon: string
- author: string
- status: string
- rank: string
- rel_type: string
- valid_taxon: taxon_basic (only present when defined)
- parent_taxon: taxon_basic
- valid: string
- fossil: string
- hier: taxon_hierarchy
- source: taxon_source
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonInfo?tnuid=30148&inst_id=0&callback=api
| Method | Return | Description |
|---|---|---|
| getTaxonInfo(tnuid:number, callback:string) | ||
| getTaxonHierarchy(tnuid:number, callback:string) | ||
| getIncludedTaxa(tnuid:number, showSyns:Y|N, showFossils:Y|N, inst_id:number, types_only:Y|N|P, show_num_spms:Y|N, callback:string) | ||
| getTaxonSynonyms(tnuid:number, showFossils:Y|N, callback:string) | ||
| getLocalities(tnuid:number, inst_id:number, precDecimals:number, showChildren:Y|N, callback:string) | ||
| getLocalities(tnuid:number, inst_id:number, pnids:array of number, precDecimals:number, showChildren:Y|N, callback:string) | ||
| getCuids(tnuids:array of number, pnids:array of number, callback:string) | ||
| getCuids(tnuid:number, showChildren:Y|N, inst_id:number, pnids:array of number, callback:string) | ||
| getTypes(tnuid:number, showSyns:Y|N, inst_id:number, primary_only:Y|N, taxon_author_search:string, offset:number, limit:number, callback:string) | ||
| getInsts(tnuid:number, callback:string) | ||
| getTaxonLiterature(tnuid:number, showSyns:Y|N, callback:string) | ||
| getAssociations(tnuid:number, rank_grouping:string, callback:string) | ||
| getHabitats(tnuid:number, callback:string) | ||
| getTaxonImages(tnuid:number, callback:string) | ||
| getTaxonBreakdown(tnuid:number, callback:string) | ||
| getTaxonPhenology(tnuid:number, callback:string) | ||
| getTaxonNewTaxaByPub(tnuid:number, validOnly:Y|N, callback:string) | ||
| getTaxonNewTaxaByYear(tnuid:number, validOnly:Y|N, callback:string) | ||
| getTaxonStatsForYear(tnuid:number, stats_year:number, callback:string) |
Occurrence / Specimen
| Method | Return | Description |
|---|---|---|
| getSpmInfo(cuid:string, callback:string) | ||
| getSpmsInfo(cuids:array of string, callback:string) |
Locality
| Method | Return | Description |
|---|---|---|
| getLocalityInfo(locID:number, tnuid:number, inst_id:number, per_id:number, pnid:number, showChildren:Y|N, completeSpmInfo:Y|N, callback:string) |
Place / Geopolitical Entity
| Method | Return | Description |
|---|---|---|
| getPlaceInfo(place_id:number, callback:string) | ||
| getSubdivisions(place_id:number, callback:string) | ||
| getGeoTaxa(place_id:number, callback:string) | ||
| getGeoCollTrips(place_id:number, callback:string) | ||
| getGeoCollTrips2(place_id:number, callback:string) | ||
| getGeoInsts(place_id:number, callback:string) |
Literature
| Method | Return | Description |
|---|---|---|
| getLitReference(pub_id:number, callback:string) | ||
| getLitParts(pub_id:number, callback:string) | ||
| getPubTaxonCitation(pub_id:number, callback:string) | ||
| getPubAssocCitation(pub_id:number, callback:string) |
Journal
| Method | Return | Description |
|---|---|---|
| getJournalInfo(jrnl_id:number, callback:string) | ||
| getJournalPubs(jrnl_id:number, callback:string) | ||
| getJournalTaxa(jrnl_id:number, callback:string) |
Institution
| Method | Return | Description |
|---|---|---|
| getCollectionInfo(inst_id:number, callback:string) | ||
| getPrimaryTypes(inst_id:number, callback:string) | ||
| getSecondaryTypes(inst_id:number, callback:string) | ||
| getInstTaxa(inst_id:number, callback:string) | ||
| getInstCollTrips2(inst_id:number, callback:string) | ||
| getInstPubs(inst_id:number, callback:string) |
Unvouchered Record
| Method | Return | Description |
|---|---|---|
| getUnvoucheredRecord(unv_id:number, callback:string) | ||
| getUnvoucheredRecords(tnuid:number, showChildren:Y|N, pnids:array of number, callback:string) | ||
| getUnvoucheredRecords(tnuids:array of number, pnids:array of number, callback:string) | ||
| getUnvLocalityInfo(locID:number, tnuid:number, per_id:number, pnid:number, showChildren:Y|N, callback:string) |
Text Search
| Method | Return | Description |
|---|---|---|
| getSearchResults(name:string, limit:number, categoryLimit:string, callback:string) | ||
| getTaxaFromText(name:string, limit:number, nameOnly:Y|N, callback:string) | ||
| getCuidsFromText(name:string, limit:number, callback:string) | ||
| getAgentsFromText(name:string, limit:number, includeParty:Y|N, callback:string) | ||
| getInstFromText(name:string, limit:number, callback:string) | ||
| getJournalsFromText(name:string, limit:number, callback:string) | ||
| getOrgsFromText(name:string, limit:number, callback:string) | ||
| getPlacesFromText(name:string, limit:number, callback:string) | ||
| getLocalitiesFromText(name:string, limit:number, callback:string) | ||
| getCollMethodsFromText(name:string, limit:number, callback:string) |
Data Type Glossary
Classes
taxon_basic
tnuid
tnuid - tnuid element
taxon
taxon - taxon element
author
author - author element
taxon_hierarchy
Kingdom
taxon_hier_unit - taxon_hier_unit class
Phylum
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Subphylum
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Class
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Subclass
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Infraclass
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Order
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Suborder
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Infraorder
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Superfamily
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Family
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Subfamily
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Tribe
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Genus
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Species
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
Subspecies
taxon_hier_unit - taxon_hier_unit class (not present if of lower rank or unspecified within the specified taxon)
taxon_hier_unit
tnuid
tnuid - tnuid element
taxon
taxon - taxon element
author
author - author element
next
String - The rank (key) of the next taxon in the taxonomic hierarchy.
taxon_source
id
String - The source identifier which uniquely identifies a taxonomic source. Will be empty when not defined.
name
String - The name for the taxonomic source.
logo
URL - A URL for the logo image for the taxonomic source.
url
URL - A URL to the taxonomic source resource.
query
URL - A URL to the taxonomic source resource for the specified taxon.
taxon_stats
included
String - The number of taxa included within this taxon.
synonym
String - The number of taxa synonymous with this taxon.
maps
String - The number of occurrence records identified to this taxon.
lits
String - The number of literature citations to this taxon.
lits_syns
String - The number of literature citations to this taxon and its synonyms.
assocs
String - The number of number of distinct biological associations for this taxon.
habitats
String - The number of number of distinct habitats for this taxon.
insts
String - The number of collections with occurrence records for this taxon.
type_syns
String - The number of type specimens for this taxon and its synonyms.
Elements
author
String - The author(s) of a taxon with parenthesis surrounding the name of the author(s) if necessary.
fossil
String - A modified boolean string, either Y, N or B, representing whether a taxon name is a extinct fossil, exclusively extant, or present today and in fossils.
inst_id
Number - The collection (or institution) identifier which uniquely identifies a collection, vouchered or unvouchered. A value of 0 indicates that all of the collections are used.
rank
String - The taxonomic (hierarchical) rank of a taxon name.
rel_type
String - The taxonomic (hierarchical) relationship between the taxonomic concept indicated by the taxon name and its parent taxonomic concept. Can be Member, Junior synonym, etc.
status
String - The nomenclatural status of a taxon name using a formalized vocabulary.
taxon
String - A taxon name string.
tnid
Number - The taxon name identifier which uniquely identifies a taxon name string.
tnuid
Number - The taxon name use identifier which uniquely identifies a taxon.
valid
String - A Valid or Invalid string representing the validity of a taxon name using subjective interpretations if warranted.
