OJ Break API Reference

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.

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonStats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonInfo?tnuid=30148&inst_id=0&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonHierarchy?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getIncludedTaxa?tnuid=491&inst_id=0&showSyns=Y&showFossils=Y&types_only=N&show_num_spms=N&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonSynonyms?tnuid=30148&showFossils=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getLocalities?tnuid=30148&inst_id=0&precDecimals=4&showChildren=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getLocalities?tnuid=30148&pnids=5816,5735&inst_id=0&precDecimals=4&showChildren=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getCuids?tnuid=30148&showChildren=Y&inst_id=1&pnids=&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getCuids?tnuids=30148,491&pnids=5816,5735&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getTypes

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getTypes?tnuid=434&showSyns=F&inst_id=1&primary_only=Y&taxon_author_search=&offset=1&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getInsts

Parameters

• tnuid: number
• format: string
• key: string

Return

• collections: array of collection_extended

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getInsts?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getTaxonLiterature (deprecated)

Description

Deprecated. Use getTaxonLit instead

Parameters

• tnuid: number
• showSyns: string
• format: string
• key: string

Return

• lit: pubs

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonLiterature?tnuid=30148&showSyns=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getTaxonLit

Description

Preferred

Parameters

• tnuid: number
• showSyns: boolean_flag
• format: string
• key: string

Return

• pubs: array of pub_extended

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonLit?tnuid=30148&showSyns=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getAssociations

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getAssociations?tnuid=491&rank_grouping=&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getHabitats

Parameters

• tnuid: number
• format: string
• key: string

Return

• habitats: array of media_basic with below extension
  • habitat: string

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getHabitats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getTaxonMedia

Parameters

• tnuid: number
• format: string
• key: string

Return

• media: array of taxon_basic with below extension
  • media_basic class

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonMedia?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getTaxonBreakdown

Parameters

• tnuid: number
• format: string
• key: string

Return

• taxa: array of taxon_basic with below extension
  • count: number
• sex: array of spm_sex

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonBreakdown?tnuid=491&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getTaxonPhenology

Parameters

• tnuid: number
• format: string
• key: string

Return

• spms: array of below elements
  • date: string
  • sort_date: string
  • cuid: string

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonPhenology?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getTaxonNewTaxaByPub

Parameters

• tnuid: number
• validOnly: boolean_flag
• format: string
• key: string

Return

• pubs: array of literature_extended with below extension
  • taxa_num: string

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonNewTaxaByPub?tnuid=491&validOnly=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getTaxonNewTaxaByYear

Parameters

• tnuid: number
• validOnly: string
• format: string
• key: string

Return

• years: array of below elements
  • taxa_num: string
  • year: string

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonNewTaxaByYear?tnuid=52&validOnly=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getTaxonStatsForYear

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxonStatsForYear?tnuid=30148&stats_year=2014&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

Occurrence / Specimen

getSpmInfo

Parameters

• cuid: string
• format: string
• key: string

Return

• spmInfo: record_vouchered

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getSpmInfo?cuid=OSUC+59557&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getSpmsInfo

Parameters

• cuids: array of string
• format: string
• key: string

Return

• spmsInfo: array of record_vouchered

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getSpmsInfo?cuids=OSUC+59557,OSUC+56308&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

Locality

getLocalityInfo

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 record_vouchered (only present if specified) or array of cuid
  • sex: array of spm_sex

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getLocalityInfo?loc_id=1&tnuid=30148&inst_id=1&per_id=1&pnid=1&showChildren=Y&completeSpmInfo=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

Place / Geopolitical Entity

getPlaceInfo

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getPlaceInfo?place_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getSubdivisions

Parameters

• place_id: number
• format: string
• key: string

Return

• subdivs: array of place

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getSubdivisions?place_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getGeoTaxa

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getGeoTaxa?place_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getGeoCollTrips

Parameters

• place_id: number
• format: string
• key: string

Return

• coll_trips: array of loc_basic with below extension
  • collector class (not yet added)

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getGeoCollTrips?place_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getGeoCollTrips2

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getGeoCollTrips2?place_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getGeoInsts

Parameters

• place_id: number
• format: string
• key: string

Return

• collections: array of collection_extended

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getGeoInsts?place_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

Literature

getLitReference

Parameters

• pub_id: number
• format: string
• key: string

Return

• pub_ref: literature_extended

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getLitReference?pub_id=419&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getLitParts

Parameters

• pub_id: number
• format: string
• key: string

Return

• pub_parts: array of literature_extended

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getLitParts?pub_id=20239&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getPubTaxonCitation

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getPubTaxonCitation?pub_id=419&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getPubAssocCitation

Parameters

• pub_id: number
• format: string
• key: string

Return

• assoc_cits: array of ..

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getPubAssocCitation?pub_id=&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

Journal

getJournalInfo

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getJournalInfo?jrnl_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getJournalPubs

Parameters

• jrnl_id: number
• format: string
• key: string

Return

• pubs: array of literature_extended

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getJournalPubs?jrnl_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getJournalTaxa

Parameters

• jrnl_id: number
• format: string
• key: string

Return

• taxa: array of taxon_basic

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getJournalTaxa?jrnl_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

Institution

getCollectionInfo

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getCollectionInfo?inst_id=21&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getPrimaryTypes

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getPrimaryTypes?inst_id=6&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getSecondaryTypes

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getSecondaryTypes?inst_id=6&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getInstTaxa

Parameters

• inst_id: number
• format: string
• key: string

Return

• taxa: array of taxon_extended with below extension
  • hier: taxon_hierarchy

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getInstTaxa?inst_id=21&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getInstCollTrips2

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getInstCollTrips2?inst_id=21&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getInstPubs

Parameters

• inst_id: number
• format: string
• key: string

Return

• pubs: array of literature_extended

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getInstPubs?inst_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

Unvouchered Record

getUnvoucheredRecord

Parameters

• unv_id: number
• format: string
• key: string

Return

• unvoucheredRecord: record_unvouchered

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getUnvoucheredRecord?unv_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getUnvoucheredRecords

Parameters

• tnuid: number
• showChildren: string
• pnids: array of number
• format: string
• key: string

Return

• unvoucheredRecords: array of record_unvouchered

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getUnvoucheredRecords?tnuid=44&showChildren=Y&pnids=&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getUnvLocalityInfo

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getUnvLocalityInfo?loc_id=1&tnuid=30148&per_id=1&pnid=1&showChildren=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

Text Search

getSearchResults

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
• 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
• 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
• journal_results: array of below extensions
  • journals: array of below extensions
    • name: string
    • id: number
  • count: number

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getSearchResults?name=Heptascelio+striatosternus&limit=20&categoryLimit=&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getTaxaFromText

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getTaxaFromText?name=Heptascelio+striatosternus&limit=10&nameOnly=N&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getCuidsFromText

Parameters

• name: string
• limit: number
• format: string
• key: string

Return

• cuids: array of cuid
• count: number

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getCuidsFromText?name=Heptascelio+striatosternus&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getAgentsFromText

Parameters

• name: string
• limit: number
• includeParty: string
• format: string
• key: string

Return

• agents:
• count: number

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getAgentsFromText?name=Heptascelio+striatosternus&limit=10&includeParty=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getInstFromText

Parameters

• name: string
• limit: number
• format: string
• key: string

Return

• inst: array of collection_extended
• count: number

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getInstFromText?name=Hymenoptera&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getJournalsFromText

Parameters

• name: string
• limit: number
• format: string
• key: string

Return

• journals: array of below elements
  • name: string
  • id: number
• count: number

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getJournalsFromText?name=Insect&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getOrgsFromText

Parameters

• name: string
• limit: number
• format: string
• key: string

Return

• orgs: array of below elements
  • name: string
  • id: number
• count: number

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getOrgsFromText?name=Heptascelio+striatosternus&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getPlacesFromText

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

http://osuc.biosci.ohio-state.edu/OJ_Break/getPlacesFromText?name=Guyana&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getLocalitiesFromText

Parameters

• name: string
• limit: number
• format: string
• key: string

Return

• locs: array of below elements
  • name: string
  • id: number
• count: number

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getLocalitiesFromText?name=Guyana&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

getCollMethodsFromText

Parameters

• name: string
• limit: number
• format: string
• key: string

Return

• coll_methods: array of below elements
  • name: string
  • id: number
• count: number

Example

http://osuc.biosci.ohio-state.edu/OJ_Break/getCollMethodsFromText?name=reared&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC

Data Type Glossary

OJ_Break API Data Type Glossary