Difference between revisions of "OJ Break API Reference"

Revision as of 16:00, 2 October 2013

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
common_names: array of common_name
orig_desc: contrib_literature_basic (only present when defined)
stats: taxon_info_stats
contribs: array of contribution

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

@@ Line 48: / Line 48: @@
 * ''hier'': taxon_hierarchy
 * ''source'': taxon_source
+* ''common_names'': array of common_name
 * ''orig_desc'': contrib_literature_basic (only present when defined)
+* ''stats'': taxon_info_stats
+* ''contribs'': array of contribution
 ====== Example ======
 http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonInfo?tnuid=30148&inst_id=0&callback=api
@@ Line 346: / Line 348: @@
 === 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.
 [[Category:OJ_Break API]]

Difference between revisions of "OJ Break API Reference"

Revision as of 16:00, 2 October 2013

Contents

Overview

Reference

Procedures

Taxon

getTaxonStats

Description

Parameters

Return

Example

getTaxonInfo

Description

Parameters

Return

Example

Occurrence / Specimen

Locality

Place / Geopolitical Entity

Literature

Journal

Institution

Unvouchered Record

Text Search

Data Type Glossary

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

Tools