Difference between revisions of "OJ Break API Reference"
(→Return) |
(→API Access) |
||
Line 4: | Line 4: | ||
− | == API Access == | + | == API Use and Access == |
Using the OJ_Break API requires calling methods with corresponding, method specific parameters (found in this page) and a few other required parameters. These include specifying a return ''format'' and an API access ''key''. | Using the OJ_Break API requires calling methods with corresponding, method specific parameters (found in this page) and a few other required parameters. These include specifying a return ''format'' and an API access ''key''. | ||
Revision as of 17:57, 6 August 2014
Introduction
OJ_Break is the name of the xBio:D RESTful API service to facilitate discovery of data within the xBio:D database. The API can respond with JavaScript Object Notation (JSON), XML, or JSON with padding (JSONP) and accepts HTTP GET and POST requests indiscriminately. The backend of the API is written in Oracle's PL/SQL database language, which is fast but often inflexible, while a Python presentation layer mitigates request handling and authentication.
Contents
- 1 API Use and Access
- 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 (deprecated)
- 2.1.13 getTaxonLit
- 2.1.14 getAssociations
- 2.1.15 getHabitats
- 2.1.16 getTaxonMedia
- 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
API Use and Access
Using the OJ_Break API requires calling methods with corresponding, method specific parameters (found in this page) and a few other required parameters. These include specifying a return format and an API access key.
Example: http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonStats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC
To read more about using the OJ_Break API, go to OJ_Break API Access.
Procedural Reference
Taxon
getTaxonStats
Description
Get some basic taxonomic statistics for a taxon from a tnuid.
Parameters
- tnuid: number
- format: string
- key: string
Return
- taxon: string
- author: string
- stats: taxon_stats
Example
getTaxonInfo
Description
Get some basic taxonomic information for a taxon from a tnuid.
Parameters
- tnuid: number
- inst_id: number
- format: string
- key: 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
getTaxonHierarchy
Description
Get the taxonomic hierarachy in which a taxon is at the terminal node from a tnuid.
Parameters
- tnuid: number
- format: string
- key: string
Return
- taxon: string
- author: string
- hier: taxon_hierarchy
Example
getIncludedTaxa
Description
Get the taxa that are directly included within a taxon but not synonymous with it.
Parameters
- tnuid: number
- inst_id: number
- showSyns: boolean_flag
- showFossils: boolean_flag
- types_only: boolean_flag
- show_num_spms: boolean_flag
- format: string
- key: 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: boolean_flag
- format: string
- key: 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: boolean_flag
- format: string
- key: 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: boolean_flag
- format: string
- key: string
Return
- localities: array of loc_coords
Example
getCuids
Description
Get the occurrence identifiers (collecting unit IDs) for a taxon.
Parameters
- tnuid: number
- showChildren: boolean_flag
- inst_id: number
- pnids: array of pnid
- format: string
- key: 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
- format: string
- key: string
Return
- cuids: array of cuid
Example
getTypes
Description
Parameters
- tnuid: number
- showSyns: boolean_flag
- inst_id: number
- primary_only: boolean_flag
- taxon_author_search: string
- offset: number
- limit: number
- format: string
- key: string
Return
- num_records: number
- types: array of taxon_basic with below extensions
- valid_taxon: taxon_basic (only present when defined)
- hier: taxon_hierarchy
- collection class
- type: string
- orig_desc: pub_extended
- images: array of below extensions
- image_id: number
- thumb: string
Example
getInsts
Description
Parameters
- tnuid: number
- format: string
- key: string
Return
- collections: array of collection_extended
Example
getTaxonLiterature (deprecated)
Description
Deprecated. Use getTaxonLit instead
Parameters
- tnuid: number
- showSyns: string
- format: string
- key: string
Return
- lit: pubs
Example
getTaxonLit
Description
Preferred
Parameters
- tnuid: number
- showSyns: boolean_flag
- format: string
- key: string
Return
- pubs: array of pub_extended
Example
getAssociations
Description
Parameters
- tnuid: number
- rank_grouping: string
- format: string
- key: string
Return
- associations: array of taxon_basic with below extensions
- type: string
- relationship: string
- hier: taxon_hierarchy
- cuids: array of cuids
Example
getHabitats
Description
Parameters
- tnuid: number
- format: string
- key: string
Return
- habitats: array of media_basic with below extension
- habitat: string
Example
getTaxonMedia
Description
Parameters
- tnuid: number
- format: string
- key: string
Return
- media: array of taxon_basic with below extension
- media_basic class
Example
getTaxonBreakdown
Description
Parameters
- tnuid: number
- format: string
- key: string
Return
- taxa: array of taxon_basic with below extension
- count: number
- sex: array of spm_sex
Example
getTaxonPhenology
Description
Parameters
- tnuid: number
- format: string
- key: string
Return
- spms: array of below elements
- date: string
- sort_date: string
- cuid: string
Example
getTaxonNewTaxaByPub
Description
Parameters
- tnuid: number
- validOnly: boolean_flag
- format: string
- key: string
Return
- pubs: array of literature_extended with below extension
- taxa_num: string
Example
getTaxonNewTaxaByYear
Description
Parameters
- tnuid: number
- validOnly: string
- format: string
- key: string
Return
- years: array of below elements
- taxa_num: string
- year: string
Example
getTaxonStatsForYear
Description
Parameters
- tnuid: number
- stats_year: number
- format: string
- key: string
Return
- stats: array of below elements
- new_spm_num: number
- all_spm_num: number
- new_taxa_spm_num: array of number
- all_taxa_spm_num: array of number
- new_images_num: number
- all_images_num: number
- spm_years: array of string
- images_years: array of string
Example
Occurrence / Specimen
getSpmInfo
Description
Parameters
- cuid: string
- format: string
- key: string
Return
- spmInfo: spm_info class with the below extensions
- loc_coords_extended class
- collector_extended class
- record class
- images: array of media_info
- collection_extended class
- associations: array of association_info with below extension
- taxon_basic class
- determinations: array of determination_extended with below extension
- taxon_basic class
Example
getSpmsInfo
Description
Parameters
- cuids: array of string
- format: string
- key: string
Return
- spmsInfo: array of spm_info class with the below extensions
- loc_coords_extended class
- collector_extended class
- record class
- images: array of media_info
- collection_extended class
- associations: array of association_info with below extension
- taxon_basic class
- determinations: array of determination_extended with below extension
- taxon_basic class
Example
Locality
getLocalityInfo
Description
Parameters
- loc_id: number
- tnuid: number
- inst_id: number
- per_id: number
- pnid: number
- showChildren: string
- completeSpmInfo: string
- format: string
- key: string
Return
- locInfo: array of loc_info with below extensions
- hier: array of place_basic
- cuids: array of cuid
- sex: ..
Example
Place / Geopolitical Entity
getPlaceInfo
Description
Parameters
- place_id: number
- format: string
- key: string
Return
- place_info: place with below extension
- hier: array of place
- num_species: number
- num_spms: number
Example
getSubdivisions
Description
Parameters
- place_id: number
- format: string
- key: string
Return
- subdivs: array of place
Example
getGeoTaxa
Description
Parameters
- place_id: number
- format: string
- key: string
Return
- taxa: array of taxon_basic with below extensions
- valid_taxon: taxon_basic (only present when defined)
- hier: taxon_hierarchy
- count: number
- rank: string
Example
getGeoCollTrips
Description
Parameters
- place_id: number
- format: string
- key: string
Return
- coll_trips: array of loc_basic with below extension
- collector class (not yet added)
Example
getGeoCollTrips2
Description
Parameters
- place_id: number
- format: string
- key: string
Return
- coll_trips: array of taxon_basic with below extensions
- collection class
- collector class (not yet added)
- loc_basic class
- valid_taxon: taxon_basic (only present when defined)
Example
getGeoInsts
Description
Parameters
- place_id: number
- format: string
- key: string
Return
- collections: array of collection_extended
Example
Literature
getLitReference
Description
Parameters
- pub_id: number
- format: string
- key: string
Return
- pub_ref: literature_extended
Example
getLitParts
Description
Parameters
- pub_id: number
- format: string
- key: string
Return
- pub_parts: array of literature_extended
Example
getPubTaxonCitation
Description
Parameters
- pub_id: number
- format: string
- key: string
Return
- pub_cits: array of pub_basic with below extensions
- taxon_basic: class
- tnucid: number
- rank: string
- public: string
- author: string
Example
getPubAssocCitation
Description
Parameters
- pub_id: number
- format: string
- key: string
Return
- assoc_cits: array of ..
Example
Journal
getJournalInfo
Description
Parameters
- jrnl_id: number
- format: string
- key: string
Return
- journal_info: array of below elements
- name: string
- url: string
- is_public: string
- copyright_holder: string
- num_articles: number
- num_pdfs: number
- num_taxa: number
- last_article_time: string
Example
getJournalPubs
Description
Parameters
- jrnl_id: number
- format: string
- key: string
Return
- pubs: array of literature_extended
Example
getJournalTaxa
Description
Parameters
- jrnl_id: number
- format: string
- key: string
Return
- taxa: array of taxon_basic
Example
Institution
getCollectionInfo
Description
Parameters
- inst_id: number
- format: string
- key: string
Return
- collection_info: array of collection_extended with below extensions
- vouchered: boolean
- num_prim_types: number
- num_sec_types: number
- num_species: number
- last_spm_time: string
- oldest_spm: array of below elements
- cuid: string
- coll_date: string
Example
getPrimaryTypes
Description
Parameters
- inst_id: number
- format: string
- key: string
Return
- types: array of taxon_basic with below extensions
- cuid: string
- type: string
- hier: taxon_hierarchy
- orig_desc: pub_extended
Example
getSecondaryTypes
Description
Parameters
- inst_id: number
- format: string
- key: string
Return
- types: array of taxon_basic with below extensions
- cuid: string
- type: string
- hier: taxon_hierarchy
- orig_desc: pub_extended
Example
getInstTaxa
Description
Parameters
- inst_id: number
- format: string
- key: string
Return
- taxa: array of taxon_extended with below extension
- hier: taxon_hierarchy
Example
getInstCollTrips2
Description
Parameters
- inst_id: number
- format: string
- key: string
Return
- coll_trips: array of taxon_basic with below extensions
- collection class
- collector class (not yet added)
- loc_basic class
Example
getInstPubs
Description
Parameters
- inst_id: number
- format: string
- key: string
Return
- pubs: array of literature_extended
Example
Unvouchered Record
getUnvoucheredRecord
Description
Parameters
- unv_id: number
- format: string
- key: string
Return
- unvoucheredRecord: spm_info class with below extensions
- unv_id: number
- loc_coords_extended class
- collector_extended class
- record class
- associations: array of association_info with below extension
- taxon_basic class
- determinations: array of determination with below extension
- taxon_basic class
Example
getUnvoucheredRecords
Description
Parameters
- tnuid: number
- showChildren: string
- pnids: array of number
- format: string
- key: string
Return
- unvoucheredRecords: array of spm_info class with below extensions
- unv_id: number
- loc_coords_extended class
- collector_extended class
- record class
- associations: array of association_info with below extension
- taxon_basic class
- determinations: array of determination with below extension
- taxon_basic class
Example
getUnvLocalityInfo
Description
Parameters
- loc_id: number
- tnuid: number
- per_id: number
- pnid: number
- showChildren: string
- format: string
- key: string
Return
- locInfo: loc_info with below extensions
- hier: array of place_basic
- cuids: array of cuid
Example
Text Search
getSearchResults
Description
Parameters
- name: string
- limit: number
- categoryLimit: string
- format: string
- key: string
Return
- taxon_results: array of below extensions
- taxa: array of taxon_extended with below extension
- lsid: number
- count: number
- taxa: array of taxon_extended with below extension
- cuid_results: array of below extensions
- cuids: array of cuids
- count: number
- agent_results: array of below extensions
- agents: array of below extensions
- type: string
- id: number
- name: string
- inst: string
- count: number
- agents: array of below extensions
- inst_results: array of below extensions
- inst: array of collection_extended
- count: number
- place_results: array of below extensions
- places: array of place_basic with below extension
- hier: array of place_basic
- count: number
- places: array of place_basic with below extension
- journal_results: array of below extensions
- journals: array of below extensions
- name: string
- id: number
- count: number
- journals: array of below extensions
Example
getTaxaFromText
Description
Parameters
- name: string
- limit: number
- nameOnly: string
- format: string
- key: string
Return
- taxa: array of taxon_extended with below extensions
- lsid: number
- count: number
Example
getCuidsFromText
Description
Parameters
- name: string
- limit: number
- format: string
- key: string
Return
- cuids: array of cuid
- count: number
Example
getAgentsFromText
Description
Parameters
- name: string
- limit: number
- includeParty: string
- format: string
- key: string
Return
- agents:
- count: number
Example
getInstFromText
Description
Parameters
- name: string
- limit: number
- format: string
- key: string
Return
- inst: array of collection_extended
- count: number
Example
getJournalsFromText
Description
Parameters
- name: string
- limit: number
- format: string
- key: string
Return
- journals: array of below elements
- name: string
- id: number
- count: number
Example
getOrgsFromText
Description
Parameters
- name: string
- limit: number
- format: string
- key: string
Return
- orgs: array of below elements
- name: string
- id: number
- count: number
Example
getPlacesFromText
Description
Parameters
- name: string
- limit: number
- format: string
- key: string
Return
- places: array of place_basic with below extension
- hier: array of place_basic
- count: number
Example
getLocalitiesFromText
Description
Parameters
- name: string
- limit: number
- format: string
- key: string
Return
- locs: array of below elements
- name: string
- id: number
- count: number
Example
getCollMethodsFromText
Description
Parameters
- name: string
- limit: number
- format: string
- key: string
Return
- coll_methods: array of below elements
- name: string
- id: number
- count: number