Difference between revisions of "OJ Break API Reference"

Revision as of 17:49, 23 May 2014

Introduction

OJ_Break is the name of the xBio:D RESTful(-like) API service to facilitate discovery of data within the xBio:D database. 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",...

Procedural Reference

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_rel_extended class with below extensions
valid_taxon: taxon_basic (only present when defined)
parent_taxon: taxon_basic
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

getTaxonHierarchy

Description

Get the taxonomic hierarachy in which a taxon is at the terminal node from a tnuid.

Parameters

tnuid: number
callback: string

Return

taxon: string
author: string
hier: taxon_hierarchy

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonHierarchy?tnuid=30148&callback=api

getIncludedTaxa

Description

Get the taxa that are directly included within a taxon but not synonymous with it.

Parameters

tnuid: number
inst_id: number
showSyns: string
showFossils: string
types_only: string
show_num_spms: boolean_flag
callback: string

Return

tnuid: number
parent_tnuid: number
includedTaxa: array of taxon_extended

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getIncludedTaxa?tnuid=491&inst_id=0&showSyns=Y&showFossils=Y&types_only=N&show_num_spms=Y&callback=api

getTaxonSynonyms

Description

Get the taxa that are objective or subjectively synonymous with a taxon.

Parameters

tnuid: number
showFossils: string
callback: string

Return

synonyms: array of taxon_rel_extended

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonSynonyms?tnuid=30148&showFossils=Y&callback=api

getLocalities

Description

Get the localities from vouchered and unvouchered records for a taxon.

Parameters

tnuid: number
inst_id: number
precDecimals: number
showChildren: string
callback: string

Return

localities: array of loc_coords

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getLocalities?tnuid=30148&inst_id=0&precDecimals=4&showChildren=Y&callback=api

getLocalities

Description

Get the localities within geopolitical divisions from vouchered and unvouchered records for a taxon.

Parameters

tnuid: number
pnids: array of pnid
inst_id: number
precDecimals: number
showChildren: string
callback: string

Return

localities: array of loc_coords

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getLocalities?tnuid=30148&pnids=5816,5735&inst_id=0&precDecimals=4&showChildren=Y&callback=api

getCuids

Description

Get the occurrence identifiers (collecting unit IDs) for a taxon.

Parameters

tnuid: number
showChildren: string
inst_id: number
pnids: array of pnid
callback: string

Return

cuids: array of cuid

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getCuids?tnuid=30148&showChildren=Y&inst_id=1&pnids=&callback=api

getCuids

Description

Get the occurrence identifiers (collecting unit IDs) for selected taxa.

Parameters

tnuids: array of tnuid
pnids: array of pnid
callback: string

Return

cuids: array of cuid

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getCuids?tnuids=30148,491&pnids=5816,5735&callback=api

getTypes

Description

Parameters

tnuid: number
showSyns: string
inst_id: number
primary_only: string
taxon_author_search: string
offset: number
limit: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTypes?tnuid=52&showSyns=F&inst_id=1&primary_only=Y&taxon_author_search=&offset=1&limit=10&callback=api

getInsts

Description

Parameters

tnuid: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getInsts?tnuid=30148&callback=api

getTaxonLiterature

Description

Deprecated

Parameters

tnuid: number
showSyns: string
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonLiterature?tnuid=30148&showSyns=Y&callback=api

getTaxonLit

Description

Preferred

Parameters

tnuid: number
showSyns: string
callback: string

Return

pubs: array of pubs

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonLit?tnuid=30148&showSyns=Y&callback=api

getAssociations

Description

Parameters

tnuid: number
rank_grouping: string
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getAssociations?tnuid=30148&rank_grouping=&callback=api

getHabitats

Description

Parameters

tnuid: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getHabitats?tnuid=30148&callback=api

getTaxonImages

Description

Parameters

tnuid: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonImages?tnuid=30148&callback=api

getTaxonBreakdown

Description

Parameters

tnuid: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonBreakdown?tnuid=30148&callback=api

getTaxonPhenology

Description

Parameters

tnuid: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonPhenology?tnuid=30148&callback=api

getTaxonNewTaxaByPub

Description

Parameters

tnuid: number
validOnly: string
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonNewTaxaByPub?tnuid=52&validOnly=Y&callback=api

getTaxonNewTaxaByYear

Description

Parameters

tnuid: number
validOnly: string
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonNewTaxaByYear?tnuid=52&validOnly=Y&callback=api

getTaxonStatsForYear

Description

Parameters

tnuid: number
stats_year: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonStatsForYear?tnuid=30148&stats_year=2014&callback=api

Occurrence / Specimen

getSpmInfo

Description

Parameters

cuid: string
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getSpmInfo?cuid=OSUC+59557&callback=api

getSpmsInfo

Description

Parameters

cuids: array of string
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getSpmsInfo?cuid=OSUC+59557&callback=api

Locality

getLocalityInfo

Description

Parameters

locID: number
tnuid: number
inst_id: number
per_id: number
pnid: number
showChildren: string
completeSpmInfo: string
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getLocalityInfo?locID=&tnuid=30148&inst_id=1&per_id&pnid=&showChildren=Y&completeSpmInfo=Y&callback=api

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

getPlaceInfo

Description

Parameters

place_id: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getPlaceInfo?place_id=&callback=api

getSubdivisions

Description

Parameters

place_id: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getSubdivisions?place_id=&callback=api

getGeoTaxa

Description

Parameters

place_id: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getGeoTaxa?place_id=&callback=api

getGeoCollTrips

Description

Parameters

place_id: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getGeoCollTrips?place_id=&callback=api

getGeoCollTrips2

Description

Parameters

place_id: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getGeoCollTrips2?place_id=&callback=api

getGeoInsts

Description

Parameters

place_id: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getGeoTaxa?place_id=&callback=api

Literature

getLitReference

Description

Parameters

pub_id: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getLitReference?pub_id=&callback=api

getLitParts

Description

Parameters

pub_id: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getLitParts?pub_id=&callback=api

getPubTaxonCitation

Description

Parameters

pub_id: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getPubTaxonCitation?pub_id=&callback=api

getPubAssocCitation

Description

Parameters

pub_id: number
callback: string

Return

Example

http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getPubAssocCitation?pub_id=&callback=api

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 316: / Line 316: @@
-{|
+=== Locality ===
-! align="left"| Method
-! align="left"| Return
+==== getLocalityInfo ====
-! align="left"| Description
+===== Description =====
-|-
-|getSpmInfo(cuid:string, callback:string)
+===== Parameters =====
-|
+* ''locID'': number
-|
+* ''tnuid'': number
-|-
+* ''inst_id'': number
-|getSpmsInfo(cuids:array of string, callback:string)
+* ''per_id'': number
-|
+* ''pnid'': number
-|
+* ''showChildren'': string
-|}
+* ''completeSpmInfo'': string
+* ''callback'': string
+===== Return =====
+*
+===== Example =====
+http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getLocalityInfo?locID=&tnuid=30148&inst_id=1&per_id&pnid=&showChildren=Y&completeSpmInfo=Y&callback=api
-=== Locality ===
 {|
 ! align="left"| Method
@@ Line 344: / Line 348: @@
 === Place / Geopolitical Entity ===
-{|
-! align="left"| Method
-! align="left"| Return
-! align="left"| 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)
-|
-|
-|}
+==== getPlaceInfo ====
+===== Description =====
+===== Parameters =====
+* ''place_id'': number
+* ''callback'': string
+===== Return =====
+*
+===== Example =====
+http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getPlaceInfo?place_id=&callback=api
+==== getSubdivisions ====
+===== Description =====
+===== Parameters =====
+* ''place_id'': number
+* ''callback'': string
+===== Return =====
+*
+===== Example =====
+http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getSubdivisions?place_id=&callback=api
+==== getGeoTaxa ====
+===== Description =====
+===== Parameters =====
+* ''place_id'': number
+* ''callback'': string
+===== Return =====
+*
+===== Example =====
+http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getGeoTaxa?place_id=&callback=api
+==== getGeoCollTrips ====
+===== Description =====
+===== Parameters =====
+* ''place_id'': number
+* ''callback'': string
+===== Return =====
+*
+===== Example =====
+http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getGeoCollTrips?place_id=&callback=api
+==== getGeoCollTrips2 ====
+===== Description =====
+===== Parameters =====
+* ''place_id'': number
+* ''callback'': string
+===== Return =====
+*
+===== Example =====
+http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getGeoCollTrips2?place_id=&callback=api
+==== getGeoInsts ====
+===== Description =====
+===== Parameters =====
+* ''place_id'': number
+* ''callback'': string
+===== Return =====
+*
+===== Example =====
+http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getGeoTaxa?place_id=&callback=api
 === Literature ===
-{|
-! align="left"| Method
+==== getLitReference ====
-! align="left"| Return
+===== Description =====
-! align="left"| Description
-|-
+===== Parameters =====
-|getLitReference(pub_id:number, callback:string)
+* ''pub_id'': number
-|
+* ''callback'': string
-|
+===== Return =====
-|-
+*
-|getLitParts(pub_id:number, callback:string)
+===== Example =====
-|
+http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getLitReference?pub_id=&callback=api
-|
-|-
+==== getLitParts ====
-|getPubTaxonCitation(pub_id:number, callback:string)
+===== Description =====
-|
-|
+===== Parameters =====
-|-
+* ''pub_id'': number
-|getPubAssocCitation(pub_id:number, callback:string)
+* ''callback'': string
-|
+===== Return =====
-|
+*
-|}
+===== Example =====
+http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getLitParts?pub_id=&callback=api
+==== getPubTaxonCitation ====
+===== Description =====
+===== Parameters =====
+* ''pub_id'': number
+* ''callback'': string
+===== Return =====
+*
+===== Example =====
+http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getPubTaxonCitation?pub_id=&callback=api
+==== getPubAssocCitation ====
+===== Description =====
+===== Parameters =====
+* ''pub_id'': number
+* ''callback'': string
+===== Return =====
+*
+===== Example =====
+http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getPubAssocCitation?pub_id=&callback=api

Difference between revisions of "OJ Break API Reference"

Revision as of 17:49, 23 May 2014

Contents

Overview

Procedural Reference

Taxon

getTaxonStats

Description

Parameters

Return

Example

getTaxonInfo

Description

Parameters

Return

Example

getTaxonHierarchy

Description

Parameters

Return

Example

getIncludedTaxa

Description

Parameters

Return

Example

getTaxonSynonyms

Description

Parameters

Return

Example

getLocalities

Description

Parameters

Return

Example

getLocalities

Description

Parameters

Return

Example

getCuids

Description

Parameters

Return

Example

getCuids

Description

Parameters

Return

Example

getTypes

Description

Parameters

Return

Example

getInsts

Description

Parameters

Return

Example

getTaxonLiterature

Description

Parameters

Return

Example

getTaxonLit

Description

Parameters

Return

Example

getAssociations

Description

Parameters

Return

Example

getHabitats

Description

Parameters

Return