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.

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
• orig_desc: contrib_literature_basic (only present when defined)

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

[OJ_Break API Data Type Glossary]

Classes

author_basic

author_id

String - The family name of the author.

last_name

String - The family name of the author.

initials

String - The initials for the given name of an author.

generation

String - The generational designation (Jr., III, etc.) for an author.

name_order

String - An indicator specifying whether an author's name should be formatted according to western (W) or eastern (E) conventions.

contrib_literature_basic (extension of literature_basic)

contrib_pub_id

pub_id - pub_id element for the contribution to the underlying publication (only present for contributions)

contrib_author_base_id

author_id - author_id element for the contributing author(s) (only present for contributions)

contrib_author

String - The comma separated list of contributing authors' family names (only present for contributions).

contrib_author_extended

Array of author_basic - array of author_basic elements for the contribution (only present for contributions)

contrib_title

String - The title for the contribution (only present for contributions).

literature_basic

pub_id

pub_id - pub_id element for the publication

type

String - The type of format in which this piece of literature was published.

author_base_id

author_id - author_id element for the author(s)

author

String - The comma separated list of authors' family names.

author_extended

Array of author_basic - array of author_basic elements for the publication

title

String - The title of the publication.

year

String - The year of publication.

month

String - The month of publication.

doi

String - The digital object identifier (DOI) assigned to a publication.

journal

String - The journal in which the article was published (only present for articles and bulletins)

journal_id

jrnl_id - jrnl_id element (only present for articles and bulletins)

series

String - The series of a journal in which an article was published (only present for articles and bulletins)

volume

String - The volume of a journal in which an article was published (only present for articles and bulletins)

vol_num

String - The part (number) within a volume of a journal in which an article was published (only present for articles and bulletins)

publisher

String - The organization that published the book (only present for books and chapters)

city

String - The city in which the book was published (only present for books and chapters)

start_page

String - The starting page of a publication (only present for articles and chapters)

end_page

String - The ending page of a publication (only present for articles and chapters)

num_pages

String - The total number of pages of a publication (only present for books, chapters, and bulletins)

chap_title

String - The title of the chapter (only present for chapters).

chap_num

String - The designation for a chapter within a book (only present for chapters).

chap_author

String - The comma separated list of chapter authors' family names (only present for chapters).

chap_author_extended

Array of author_basic - array of author_basic elements for the chapter (only present for chapters)

book_id

pub_id - pub_id element of the book for a chapter (only present for chapters)

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 (extension of taxon_basic)

next

String - The rank (key) of the next taxon in the taxonomic hierarchy. This value is null on the last taxon in the 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.

author_id

Number - The author identifier which uniquely identifies an author or group of authors.

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.

jrnl_id

Number - The journal identifier which uniquely identifies a journal.

pub_id

Number - The publication identifier which uniquely identifies a publication.

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.