Difference between revisions of "OJ Break API Reference"
| Line 171: | Line 171: | ||
* ''callback'': string | * ''callback'': string | ||
===== Return ===== | ===== Return ===== | ||
| − | * | + | * ''collections'': array of .. (inst_id, inst_name, inst_code, spm_count) |
===== Example ===== | ===== Example ===== | ||
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getInsts?tnuid=30148&callback=api | http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getInsts?tnuid=30148&callback=api | ||
| Line 183: | Line 183: | ||
* ''callback'': string | * ''callback'': string | ||
===== Return ===== | ===== Return ===== | ||
| − | * | + | * ''lit'': pubs |
===== Example ===== | ===== Example ===== | ||
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonLiterature?tnuid=30148&showSyns=Y&callback=api | http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonLiterature?tnuid=30148&showSyns=Y&callback=api | ||
| Line 207: | Line 207: | ||
* ''callback'': string | * ''callback'': string | ||
===== Return ===== | ===== Return ===== | ||
| − | * | + | * ''associations'': array of .. (taxon_basic class, type, relationship, hier, cuids) |
===== Example ===== | ===== Example ===== | ||
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getAssociations?tnuid=30148&rank_grouping=&callback=api | http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getAssociations?tnuid=30148&rank_grouping=&callback=api | ||
| Line 218: | Line 218: | ||
* ''callback'': string | * ''callback'': string | ||
===== Return ===== | ===== Return ===== | ||
| − | * | + | * ''habitats'': array of .. (habitat, images) |
===== Example ===== | ===== Example ===== | ||
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getHabitats?tnuid=30148&callback=api | http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getHabitats?tnuid=30148&callback=api | ||
| Line 229: | Line 229: | ||
* ''callback'': string | * ''callback'': string | ||
===== Return ===== | ===== Return ===== | ||
| − | * | + | * ''images'': array of .. (image/media_basic extension) |
===== Example ===== | ===== Example ===== | ||
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonImages?tnuid=30148&callback=api | http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonImages?tnuid=30148&callback=api | ||
| Line 240: | Line 240: | ||
* ''callback'': string | * ''callback'': string | ||
===== Return ===== | ===== Return ===== | ||
| − | * | + | * ''taxa'': array of .. (taxon_basic, count) |
| + | * ''sex'': array of .. (U,M,F,N,null) | ||
===== Example ===== | ===== Example ===== | ||
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonBreakdown?tnuid=30148&callback=api | http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonBreakdown?tnuid=30148&callback=api | ||
| Line 251: | Line 252: | ||
* ''callback'': string | * ''callback'': string | ||
===== Return ===== | ===== Return ===== | ||
| − | * | + | * ''spms'': array of .. (date, sort_date, cuid) |
===== Example ===== | ===== Example ===== | ||
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonPhenology?tnuid=30148&callback=api | http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonPhenology?tnuid=30148&callback=api | ||
| Line 263: | Line 264: | ||
* ''callback'': string | * ''callback'': string | ||
===== Return ===== | ===== Return ===== | ||
| − | * | + | * ''pubs'': array of .. (taxa_num, pub_ref) |
===== Example ===== | ===== Example ===== | ||
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonNewTaxaByPub?tnuid=491&validOnly=Y&callback=api | http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonNewTaxaByPub?tnuid=491&validOnly=Y&callback=api | ||
| Line 275: | Line 276: | ||
* ''callback'': string | * ''callback'': string | ||
===== Return ===== | ===== Return ===== | ||
| − | * | + | * ''years'': array of .. (taxa_num, year) |
===== Example ===== | ===== Example ===== | ||
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonNewTaxaByYear?tnuid=52&validOnly=Y&callback=api | http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonNewTaxaByYear?tnuid=52&validOnly=Y&callback=api | ||
| Line 287: | Line 288: | ||
* ''callback'': string | * ''callback'': string | ||
===== Return ===== | ===== Return ===== | ||
| − | * | + | * ''stats'': array of .. (new_spm_num, all_spm_num, new_taxa_spm_num, all_taxa_spm_num, new_images_num, all_images_num, spm_years, images_years) |
===== Example ===== | ===== Example ===== | ||
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonStatsForYear?tnuid=30148&stats_year=2014&callback=api | http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonStatsForYear?tnuid=30148&stats_year=2014&callback=api | ||
Revision as of 17:20, 27 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.
Contents
- 1 Overview
- 2 Procedural Reference
- 2.1 Taxon
- 2.1.1 getTaxonStats
- 2.1.2 getTaxonInfo
- 2.1.3 getTaxonHierarchy
- 2.1.4 getIncludedTaxa
- 2.1.5 getTaxonSynonyms
- 2.1.6 getLocalities
- 2.1.7 getLocalities
- 2.1.8 getCuids
- 2.1.9 getCuids
- 2.1.10 getTypes
- 2.1.11 getInsts
- 2.1.12 getTaxonLiterature
- 2.1.13 getTaxonLit
- 2.1.14 getAssociations
- 2.1.15 getHabitats
- 2.1.16 getTaxonImages
- 2.1.17 getTaxonBreakdown
- 2.1.18 getTaxonPhenology
- 2.1.19 getTaxonNewTaxaByPub
- 2.1.20 getTaxonNewTaxaByYear
- 2.1.21 getTaxonStatsForYear
- 2.2 Occurrence / Specimen
- 2.3 Locality
- 2.4 Place / Geopolitical Entity
- 2.5 Literature
- 2.6 Journal
- 2.7 Institution
- 2.8 Unvouchered Record
- 2.9 Text Search
- 2.1 Taxon
- 3 Data Type Glossary
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
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
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
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
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
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
getTypes
Description
Parameters
- tnuid: number
- showSyns: string
- inst_id: number
- primary_only: string
- taxon_author_search: string
- offset: number
- limit: number
- callback: string
Return
- Types: array of ..
- num_records: number
Example
getInsts
Description
Parameters
- tnuid: number
- callback: string
Return
- collections: array of .. (inst_id, inst_name, inst_code, spm_count)
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
- lit: pubs
Example
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
- associations: array of .. (taxon_basic class, type, relationship, hier, cuids)
Example
getHabitats
Description
Parameters
- tnuid: number
- callback: string
Return
- habitats: array of .. (habitat, images)
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getHabitats?tnuid=30148&callback=api
getTaxonImages
Description
Parameters
- tnuid: number
- callback: string
Return
- images: array of .. (image/media_basic extension)
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonImages?tnuid=30148&callback=api
getTaxonBreakdown
Description
Parameters
- tnuid: number
- callback: string
Return
- taxa: array of .. (taxon_basic, count)
- sex: array of .. (U,M,F,N,null)
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getTaxonBreakdown?tnuid=30148&callback=api
getTaxonPhenology
Description
Parameters
- tnuid: number
- callback: string
Return
- spms: array of .. (date, sort_date, cuid)
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
- pubs: array of .. (taxa_num, pub_ref)
Example
getTaxonNewTaxaByYear
Description
Parameters
- tnuid: number
- validOnly: string
- callback: string
Return
- years: array of .. (taxa_num, year)
Example
getTaxonStatsForYear
Description
Parameters
- tnuid: number
- stats_year: number
- callback: string
Return
- stats: array of .. (new_spm_num, all_spm_num, new_taxa_spm_num, all_taxa_spm_num, new_images_num, all_images_num, spm_years, images_years)
Example
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
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
getJournalInfo
Description
Parameters
- jrnl_id: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getJournalInfo?jrnl_id=&callback=api
getJournalPubs
Description
Parameters
- jrnl_id: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getJournalPubs?jrnl_id=&callback=api
getJournalTaxa
Description
Parameters
- jrnl_id: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getJournalTaxa?jrnl_id=&callback=api
Institution
getCollectionInfo
Description
Parameters
- inst_id: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getCollectionInfo?inst_id=21&callback=api
getPrimaryTypes
Description
Parameters
- inst_id: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getPrimaryTypes?inst_id=6&callback=api
getSecondaryTypes
Description
Parameters
- inst_id: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getSecondaryTypes?inst_id=6&callback=api
getInstTaxa
Description
Parameters
- inst_id: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getInstTaxa?inst_id=21&callback=api
getInstCollTrips2
Description
Parameters
- inst_id: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getInstCollTrips2?inst_id=21&callback=api
getInstPubs
Description
Parameters
- inst_id: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getInstPubs?inst_id=1&callback=api
Unvouchered Record
getUnvoucheredRecord
Description
Parameters
- univ_id: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getUnvoucheredRecord?univ_id=1&callback=api
getUnvoucheredRecords
Description
Parameters
- tnuid: number
- showChildren: string
- pnids: array of number
- callback: string
Return
Example
getUnvoucheredRecords
Description
Parameters
- tnuid: number
- pnids: array of number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getUnvoucheredRecords?univ_id=1&pnids=&callback=api
getUnvLocalityInfo
Description
Parameters
- locID: number
- tnuid: number
- per_id: number
- pnid: number
- showChildren: string
- callback: string
Return
Example
Text Search
getSearchResults
Description
Parameters
- name: string
- limit: number
- categoryLimit: string
- callback: string
Return
Example
getTaxaFromText
Description
Parameters
- name: string
- limit: number
- nameOnly: string
- callback: string
Return
Example
getCuidsFromText
Description
Parameters
- name: string
- limit: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getCuidsFromText?name=&limit=&callback=api
getAgentsFromText
Description
Parameters
- name: string
- limit: number
- includeParty: string
- callback: string
Return
Example
getInstFromText
Description
Parameters
- name: string
- limit: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getInstFromText?name=&limit=&callback=api
getJournalsFromText
Description
Parameters
- name: string
- limit: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getJournalsFromText?name=&limit=&callback=api
getOrgsFromText
Description
Parameters
- name: string
- limit: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getOrgsFromText?name=&limit=&callback=api
getPlacesFromText
Description
Parameters
- name: string
- limit: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getPlacesFromText?name=&limit=&callback=api
getLocalitiesFromText
Description
Parameters
- name: string
- limit: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getLocalitiesFromText?name=&limit=&callback=api
getCollMethodsFromText
Description
Parameters
- name: string
- limit: number
- callback: string
Return
Example
http://osuc.biosci.ohio-state.edu/hymDB/OJ_Break.getCollMethodsFromText?name=&limit=&callback=api
