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

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