Difference between revisions of "OJ Break API Reference"
(Updated the page to point to the new api urls.) |
|||
(249 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
'''Introduction''' | '''Introduction''' | ||
− | OJ_Break is the name of the xBio:D RESTful | + | 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. |
− | + | The reference for version 2 of the API can be found here: [[OJ_Break_Version_2_API_Reference]] | |
− | |||
− | |||
− | |||
− | |||
+ | == API Information and Access == | ||
+ | This page specifies the methods and data defined by OJ_Break Version 1. Using the OJ_Break Version 1 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: https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonStats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | ||
+ | |||
+ | To read more about using the OJ_Break Version 1 API, go to [[OJ_Break API Access]]. | ||
== Procedural Reference == | == Procedural Reference == | ||
+ | === Agent === | ||
+ | ==== getCollectorInfo ==== | ||
+ | ===== Description ===== | ||
+ | ===== Parameters ===== | ||
+ | * ''collector_id'': number | ||
+ | * ''format'': string | ||
+ | * ''key'': string | ||
+ | ===== Return ===== | ||
+ | * ''collector_info'': array of author_info | ||
+ | |||
+ | ===== Example ===== | ||
+ | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getCollectorInfo?collector_id=2&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | ||
+ | |||
+ | ==== getAuthorPubs ==== | ||
+ | ===== Description ===== | ||
+ | ===== Parameters ===== | ||
+ | * ''author_id'': number | ||
+ | * ''format'': string | ||
+ | * ''key'': string | ||
+ | ===== Return ===== | ||
+ | * ''pubs'': array of literature_extended | ||
+ | |||
+ | ===== Example ===== | ||
+ | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getAuthorPubs?author_id=2&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | ||
+ | |||
+ | ==== getCollTrips2 ==== | ||
+ | ===== Description ===== | ||
+ | ===== Parameters ===== | ||
+ | * ''collector_id'': number | ||
+ | * ''format'': string | ||
+ | * ''key'': string | ||
+ | ===== Return ===== | ||
+ | * ''coll_trips'': array of collection_basic, taxon_basic, loc_coords, and collector. | ||
+ | |||
+ | ===== Example ===== | ||
+ | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getCollTrips2?collector_id=2&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | ||
+ | |||
+ | ==== getAuthorTaxa ==== | ||
+ | ===== Description ===== | ||
+ | ===== Parameters ===== | ||
+ | * ''author_id'': number | ||
+ | * ''format'': string | ||
+ | * ''key'': string | ||
+ | |||
+ | ===== Return ===== | ||
+ | ''taxa'': array of taxon_basic | ||
+ | |||
+ | ===== Example ===== | ||
+ | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getAuthorTaxa?author_id=2&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | ||
+ | |||
=== Taxon === | === Taxon === | ||
==== getTaxonStats ==== | ==== getTaxonStats ==== | ||
Line 19: | Line 71: | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
===== Return ===== | ===== Return ===== | ||
* ''taxon'': string | * ''taxon'': string | ||
Line 26: | Line 79: | ||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonStats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getTaxonInfo ==== | ==== getTaxonInfo ==== | ||
Line 34: | Line 87: | ||
* ''tnuid'': number | * ''tnuid'': number | ||
* ''inst_id'': number | * ''inst_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
===== Return ===== | ===== Return ===== | ||
* ''taxon_rel_extended'' class with below extensions | * ''taxon_rel_extended'' class with below extensions | ||
Line 46: | Line 100: | ||
* ''contribs'': array of contribution | * ''contribs'': array of contribution | ||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonInfo?tnuid=30148&inst_id=0&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getTaxonHierarchy ==== | ==== getTaxonHierarchy ==== | ||
Line 53: | Line 107: | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
===== Return ===== | ===== Return ===== | ||
* ''taxon'': string | * ''taxon'': string | ||
Line 59: | Line 114: | ||
* ''hier'': taxon_hierarchy | * ''hier'': taxon_hierarchy | ||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonHierarchy?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getIncludedTaxa ==== | ==== getIncludedTaxa ==== | ||
Line 67: | Line 122: | ||
* ''tnuid'': number | * ''tnuid'': number | ||
* ''inst_id'': number | * ''inst_id'': number | ||
− | * ''showSyns'': | + | * ''showSyns'': boolean_flag |
− | * ''showFossils'': | + | * ''showFossils'': boolean_flag |
− | * ''types_only'': | + | * ''types_only'': boolean_flag |
* ''show_num_spms'': boolean_flag | * ''show_num_spms'': boolean_flag | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
Line 77: | Line 134: | ||
* ''includedTaxa'': array of taxon_extended | * ''includedTaxa'': array of taxon_extended | ||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getIncludedTaxa?tnuid=491&inst_id=0&showSyns=Y&showFossils=Y&types_only=N&show_num_spms=N&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getTaxonSynonyms ==== | ==== getTaxonSynonyms ==== | ||
===== Description ===== | ===== Description ===== | ||
− | Get the taxa that are | + | Get the taxa that are objectively or subjectively synonymous with a taxon. |
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
− | * ''showFossils'': string | + | * ''showFossils'': boolean_flag |
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
* ''synonyms'': array of taxon_rel_extended | * ''synonyms'': array of taxon_rel_extended | ||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonSynonyms?tnuid=30148&showFossils=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getLocalities ==== | ==== getLocalities ==== | ||
Line 98: | Line 157: | ||
* ''inst_id'': number | * ''inst_id'': number | ||
* ''precDecimals'': number | * ''precDecimals'': number | ||
− | * ''showChildren'': string | + | * ''showChildren'': boolean_flag |
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
* ''localities'': array of loc_coords | * ''localities'': array of loc_coords | ||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getLocalities?tnuid=30148&inst_id=0&precDecimals=4&showChildren=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getLocalities ==== | ==== getLocalities ==== | ||
Line 113: | Line 174: | ||
* ''inst_id'': number | * ''inst_id'': number | ||
* ''precDecimals'': number | * ''precDecimals'': number | ||
− | * ''showChildren'': string | + | * ''showChildren'': boolean_flag |
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
* ''localities'': array of loc_coords | * ''localities'': array of loc_coords | ||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getLocalities?tnuid=30148&pnids=5816,5735&inst_id=0&precDecimals=4&showChildren=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getCuids ==== | ==== getCuids ==== | ||
Line 125: | Line 188: | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
− | * ''showChildren'': | + | * ''showChildren'': boolean_flag |
* ''inst_id'': number | * ''inst_id'': number | ||
* ''pnids'': array of pnid | * ''pnids'': array of pnid | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
* ''cuids'': array of cuid | * ''cuids'': array of cuid | ||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getCuids?tnuid=30148&showChildren=Y&inst_id=1&pnids=&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getCuids ==== | ==== getCuids ==== | ||
Line 140: | Line 205: | ||
* ''tnuids'': array of tnuid | * ''tnuids'': array of tnuid | ||
* ''pnids'': array of pnid | * ''pnids'': array of pnid | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
* ''cuids'': array of cuid | * ''cuids'': array of cuid | ||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getCuids?tnuids=30148,491&pnids=5816,5735&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getTypes ==== | ==== getTypes ==== | ||
===== Description ===== | ===== Description ===== | ||
+ | Gets information and specimen types for a specified taxon. | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
− | * ''showSyns'': | + | * ''showSyns'': boolean_flag |
* ''inst_id'': number | * ''inst_id'': number | ||
− | * ''primary_only'': | + | * ''primary_only'': boolean_flag |
* ''taxon_author_search'': string | * ''taxon_author_search'': string | ||
* ''offset'': number | * ''offset'': number | ||
* ''limit'': number | * ''limit'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | |||
* ''num_records'': number | * ''num_records'': number | ||
+ | * ''types'': array of type_extended | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTypes?tnuid=434&showSyns=F&inst_id=1&primary_only=Y&taxon_author_search=&offset=1&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getInsts ==== | ==== getInsts ==== | ||
===== Description ===== | ===== Description ===== | ||
+ | Gets institutions which hold specimens for a selected taxon. | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''collections'': array of | + | * ''collections'': array of collection_extended |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getInsts?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
− | ==== getTaxonLiterature ==== | + | ==== getTaxonLiterature (deprecated) ==== |
===== Description ===== | ===== Description ===== | ||
− | Deprecated | + | Deprecated. Use getTaxonLit instead |
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
* ''showSyns'': string | * ''showSyns'': string | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
* ''lit'': pubs | * ''lit'': pubs | ||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonLiterature?tnuid=30148&showSyns=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getTaxonLit ==== | ==== getTaxonLit ==== | ||
===== Description ===== | ===== Description ===== | ||
− | Preferred | + | Preferred. Get literature for a selected taxon. |
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
− | * ''showSyns'': string | + | * ''showSyns'': boolean_flag |
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''pubs'': array of | + | * ''pubs'': array of pub_extended |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonLit?tnuid=30148&showSyns=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getAssociations ==== | ==== getAssociations ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get evolutionary relationships for a certain taxon. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
* ''rank_grouping'': string | * ''rank_grouping'': string | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''associations'': array of | + | * ''associations'': array of association |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getAssociations?tnuid=491&rank_grouping=&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getHabitats ==== | ==== getHabitats ==== | ||
===== Description ===== | ===== Description ===== | ||
+ | Get descriptions of the habitats that a selected specimen inhabits. | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''habitats'': array of | + | * ''habitats'': array of habitat |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getHabitats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
− | ==== | + | ==== getTaxonMedia ==== |
===== Description ===== | ===== Description ===== | ||
− | + | Get images, videos, or sound clips of a selected taxon. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * '' | + | * ''media'': array of media_basic |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonMedia?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getTaxonBreakdown ==== | ==== getTaxonBreakdown ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get count of genders and total specimen included in the current rank. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''taxa'': array of | + | * ''taxa'': array of taxon_basic with below extension |
− | * ''sex'': array of | + | ** ''count'': number |
+ | * ''sex'': array of spm_sex | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonBreakdown?tnuid=491&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getTaxonPhenology ==== | ==== getTaxonPhenology ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get taxon specimens by date. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''spms'': array of | + | * ''spms'': array of below elements |
+ | ** ''date'': string | ||
+ | ** ''sort_date'': string | ||
+ | ** ''cuid'': string | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonPhenology?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getTaxonNewTaxaByPub ==== | ==== getTaxonNewTaxaByPub ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get count of new specimens for a specific taxon by publication. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
− | * ''validOnly'': string | + | * ''validOnly'': boolean_flag |
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''pubs'': array of | + | * ''pubs'': array of literature_extended with below extension |
+ | ** ''taxa_num'': string | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonNewTaxaByPub?tnuid=491&validOnly=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getTaxonNewTaxaByYear ==== | ==== getTaxonNewTaxaByYear ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get count of new specimens for a specific taxon by year. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
* ''validOnly'': string | * ''validOnly'': string | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''years'': array of | + | * ''years'': array of below elements |
+ | ** ''taxa_num'': string | ||
+ | ** ''year'': string | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonNewTaxaByYear?tnuid=52&validOnly=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getTaxonStatsForYear ==== | ==== getTaxonStatsForYear ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get stats, such as image count, new genera introduced, new specimen introduced, and more by year for a selected taxon. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''tnuid'': number | * ''tnuid'': number | ||
* ''stats_year'': number | * ''stats_year'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''stats'': array of | + | * ''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 ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonStatsForYear?tnuid=30148&stats_year=2014&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
− | |||
− | |||
− | |||
− | |||
− | ===== Parameters ===== | + | === Occurrence === |
+ | ==== Specimen Record ==== | ||
+ | ===== getSpmInfo ===== | ||
+ | ====== Description ====== | ||
+ | Get info for a specific specimen occurrence. | ||
+ | ====== Parameters ====== | ||
* ''cuid'': string | * ''cuid'': string | ||
− | * '' | + | * ''format'': string |
− | + | * ''key'': string | |
− | * '' | ||
− | |||
− | |||
− | ==== | + | ====== Return ====== |
− | ===== | + | * ''spmInfo'': record_vouchered |
+ | ====== Example ====== | ||
+ | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getSpmInfo?cuid=OSUC+59557&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | ||
− | ===== Parameters ===== | + | ===== getSpmsInfo ===== |
+ | ====== Description ====== | ||
+ | Get info for multiple specimen occurrences. | ||
+ | ====== Parameters ====== | ||
* ''cuids'': array of string | * ''cuids'': array of string | ||
− | * '' | + | * ''format'': string |
− | ===== Return ===== | + | * ''key'': string |
− | * ''spmsInfo'': array of | + | |
− | ===== Example ===== | + | ====== Return ====== |
− | + | * ''spmsInfo'': array of record_vouchered | |
+ | ====== Example ====== | ||
+ | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getSpmsInfo?cuids=OSUC+59557,OSUC+56308&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | ||
+ | |||
+ | ==== Unvouchered Record ==== | ||
+ | ===== getUnvoucheredRecord ===== | ||
+ | ====== Description ====== | ||
+ | Get specimen record information for a selected unvouchered specimen. | ||
+ | ====== Parameters ====== | ||
+ | * ''unv_id'': number | ||
+ | * ''format'': string | ||
+ | * ''key'': string | ||
+ | |||
+ | ====== Return ====== | ||
+ | * ''unvoucheredRecord'': record_unvouchered | ||
+ | |||
+ | ====== Example ====== | ||
+ | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getUnvoucheredRecord?unv_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | ||
+ | |||
+ | ===== getUnvoucheredRecords ===== | ||
+ | ====== Description ====== | ||
+ | Get unvouchered specimen records for a selected taxon and place. | ||
+ | ====== Parameters ====== | ||
+ | * ''tnuid'': number | ||
+ | * ''showChildren'': string | ||
+ | * ''pnids'': array of number | ||
+ | * ''format'': string | ||
+ | * ''key'': string | ||
+ | |||
+ | ====== Return ====== | ||
+ | * ''unvoucheredRecords'': array of record_unvouchered | ||
+ | |||
+ | ====== Example ====== | ||
+ | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getUnvoucheredRecords?tnuid=44&showChildren=Y&pnids=&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | ||
=== Locality === | === Locality === | ||
==== getLocalityInfo ==== | ==== getLocalityInfo ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get basic information for a specific locality, including specimen occurrences, place hierarchy, and coordinates. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''loc_id'': number | * ''loc_id'': number | ||
Line 327: | Line 483: | ||
* ''showChildren'': string | * ''showChildren'': string | ||
* ''completeSpmInfo'': string | * ''completeSpmInfo'': string | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''locInfo'': array of loc_info with below extensions |
+ | ** ''hier'': array of place | ||
+ | ** ''cuids'': array of record_vouchered (only present if specified) or array of cuid | ||
+ | ** ''sex'': array of spm_sex | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getLocalityInfo?loc_id=1&tnuid=30148&inst_id=1&per_id=1&pnid=1&showChildren=Y&completeSpmInfo=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
+ | |||
+ | ==== getUnvLocalityInfo ==== | ||
+ | ===== Description ===== | ||
+ | Get locality information and occurrences (specimens) for a selected locality. The request can be narrowed down further by selected multiple parameter options. | ||
+ | ===== 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 | ||
+ | ** ''cuids'': array of cuid | ||
+ | |||
+ | ===== Example ===== | ||
+ | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getUnvLocalityInfo?loc_id=1&tnuid=30148&per_id=1&pnid=1&showChildren=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | ||
=== Place / Geopolitical Entity === | === Place / Geopolitical Entity === | ||
==== getPlaceInfo ==== | ==== getPlaceInfo ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get basic place information including the place hierarchy, number of specimens, and number of species. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''place_id'': number | * ''place_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''place_info'': place with below extension |
+ | ** ''hier'': array of place | ||
+ | ** ''num_species'': number | ||
+ | ** ''num_spms'': number | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getPlaceInfo?place_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getSubdivisions ==== | ==== getSubdivisions ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get smaller levels of divisions for a selected place. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''place_id'': number | * ''place_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''subdivs'': array of place |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getSubdivisions?place_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getGeoTaxa ==== | ==== getGeoTaxa ==== | ||
===== Description ===== | ===== Description ===== | ||
+ | Get taxonomic information from a specified place. | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''place_id'': number | * ''place_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== 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 ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getGeoTaxa?place_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getGeoCollTrips ==== | ==== getGeoCollTrips ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get collecting trips info for a specified place. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''place_id'': number | * ''place_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''coll_trips'': array of loc_basic and collector. |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getGeoCollTrips?place_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getGeoCollTrips2 ==== | ==== getGeoCollTrips2 ==== | ||
===== Description ===== | ===== Description ===== | ||
+ | Get collecting trips and taxa info for a specified place. | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''place_id'': number | * ''place_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''coll_trips'': array of taxon_basic, collection, collector and loc_basic with below extension |
+ | ** ''valid_taxon'': taxon_basic (only present when defined) | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getGeoCollTrips2?place_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getGeoInsts ==== | ==== getGeoInsts ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get institutions from a selected place. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''place_id'': number | * ''place_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''collections'': array of collection_extended |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getGeoInsts?place_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
=== Literature === | === Literature === | ||
==== getLitReference ==== | ==== getLitReference ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get the reference for a selected publication. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''pub_id'': number | * ''pub_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''pub_ref'': literature_extended |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getLitReference?pub_id=419&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getLitParts ==== | ==== getLitParts ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get parts of the selected publication, such as pages, pdf urls, chapters, titles, authors, and more. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''pub_id'': number | * ''pub_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''pub_parts'': array of literature_extended |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getLitParts?pub_id=20239&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getPubTaxonCitation ==== | ==== getPubTaxonCitation ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get cited taxon information from a selected publication. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''pub_id'': number | * ''pub_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''pub_cits'': array of pub_basic and taxon_basic with below extensions |
+ | ** ''tnucid'': number | ||
+ | ** ''rank'': string | ||
+ | * ''public'': string | ||
+ | * ''author'': string | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getPubTaxonCitation?pub_id=419&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getPubAssocCitation ==== | ==== getPubAssocCitation ==== | ||
Line 439: | Line 662: | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''pub_id'': number | * ''pub_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''assoc_cits'': array of .. |
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getPubAssocCitation?pub_id=23683&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
=== Journal === | === Journal === | ||
Line 451: | Line 676: | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''jrnl_id'': number | * ''jrnl_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== 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 ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getJournalInfo?jrnl_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getJournalPubs ==== | ==== getJournalPubs ==== | ||
Line 462: | Line 698: | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''jrnl_id'': number | * ''jrnl_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''pubs'': array of literature_extended |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getJournalPubs?jrnl_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getJournalTaxa ==== | ==== getJournalTaxa ==== | ||
Line 473: | Line 712: | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''jrnl_id'': number | * ''jrnl_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''taxa'': array of taxon_basic |
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getJournalTaxa?jrnl_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
=== Institution === | === Institution === | ||
Line 485: | Line 726: | ||
===== Parameters ===== | ===== Parameters ===== | ||
* ''inst_id'': number | * ''inst_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''collection_info'': array of | + | * ''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 ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getCollectionInfo?inst_id=21&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getPrimaryTypes ==== | ==== getPrimaryTypes ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get specimen of which the description of a new species is based. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''inst_id'': number | * ''inst_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''types'': array of | + | * ''types'': array of type |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getPrimaryTypes?inst_id=6&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getSecondaryTypes ==== | ==== getSecondaryTypes ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get specimen that are occurrences of a specific species, but not a primary type. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''inst_id'': number | * ''inst_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''types'': array of | + | * ''types'': array of type |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getSecondaryTypes?inst_id=6&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getInstTaxa ==== | ==== getInstTaxa ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get taxa and related taxonomic information from a selected institution. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''inst_id'': number | * ''inst_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''taxa'': array of | + | * ''taxa'': array of taxon_extended with below extension |
+ | ** ''hier'': taxon_hierarchy | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getInstTaxa?inst_id=21&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getInstCollTrips2 ==== | ==== getInstCollTrips2 ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get collecting trip events and the specimen collected for a selected institution. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''inst_id'': number | * ''inst_id'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * ''coll_trips'': array of . | + | * ''coll_trips'': array of taxon_basic, collection, collector, and loc_basic. |
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getInstCollTrips2?inst_id=21&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getInstPubs ==== | ==== getInstPubs ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get published literature from a selected institution. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''inst_id'': number | * ''inst_id'': number | ||
− | * '' | + | * ''format'': string |
− | + | * ''key'': string | |
− | * '' | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''pubs'': array of literature_extended |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getInstPubs?inst_id=1&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
=== Text Search === | === Text Search === | ||
==== getSearchResults ==== | ==== getSearchResults ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get database results from a text keyword search. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''name'': string | * ''name'': string | ||
* ''limit'': number | * ''limit'': number | ||
* ''categoryLimit'': string | * ''categoryLimit'': string | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== 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 with below extension | ||
+ | *** ''hier'': array of place | ||
+ | ** ''count'': number | ||
+ | * ''journal_results'': array of below extensions | ||
+ | ** ''journals'': array of below extensions | ||
+ | *** ''name'': string | ||
+ | *** ''id'': number | ||
+ | ** ''count'': number | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getSearchResults?name=%OSU%&limit=20&categoryLimit=&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getTaxaFromText ==== | ==== getTaxaFromText ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get taxa results from a selected search keyword. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''name'': string | * ''name'': string | ||
* ''limit'': number | * ''limit'': number | ||
* ''nameOnly'': string | * ''nameOnly'': string | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''taxa'': array of taxon_extended with below extensions |
+ | ** ''lsid'': number | ||
+ | * ''count'': number | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxaFromText?name=Heptascelio+striatosternus&limit=10&nameOnly=N&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getCuidsFromText ==== | ==== getCuidsFromText ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get occurrence results from a selected search keyword. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''name'': string | * ''name'': string | ||
* ''limit'': number | * ''limit'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''cuids'': array of cuid |
+ | * ''count'': number | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getCuidsFromText?name=%OSUC%&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getAgentsFromText ==== | ==== getAgentsFromText ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get agent (person and/or party) results from a selected search keyword. | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''name'': string | * ''name'': string | ||
* ''limit'': number | * ''limit'': number | ||
* ''includeParty'': string | * ''includeParty'': string | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''agents'': array of below elements |
+ | ** ''id'': number | ||
+ | ** ''type'': string | ||
+ | ** ''name'': string | ||
+ | ** ''inst'': string | ||
+ | * ''count'': number | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getAgentsFromText?name=%Johnson,%20N.%20F.%&limit=10&includeParty=Y&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getInstFromText ==== | ==== getInstFromText ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get institution/collection results from a selected search keyword(s). | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''name'': string | * ''name'': string | ||
* ''limit'': number | * ''limit'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''inst'': array of collection_extended |
+ | * ''count'': number | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getInstFromText?name=Hymenoptera&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getJournalsFromText ==== | ==== getJournalsFromText ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get journal results from a selected search keyword(s). | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''name'': string | * ''name'': string | ||
* ''limit'': number | * ''limit'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''journals'': array of below elements |
+ | ** ''name'': string | ||
+ | ** ''id'': number | ||
+ | * ''count'': number | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getJournalsFromText?name=Insect&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getOrgsFromText ==== | ==== getOrgsFromText ==== | ||
===== Description ===== | ===== Description ===== | ||
− | + | Get organization results for a selected search keyword(s). | |
===== Parameters ===== | ===== Parameters ===== | ||
* ''name'': string | * ''name'': string | ||
* ''limit'': number | * ''limit'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''orgs'': array of below elements |
+ | ** ''name'': string | ||
+ | ** ''id'': number | ||
+ | * ''count'': number | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getOrgsFromText?name=%Geo%&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getPlacesFromText ==== | ==== getPlacesFromText ==== | ||
Line 692: | Line 969: | ||
* ''name'': string | * ''name'': string | ||
* ''limit'': number | * ''limit'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''places'': array of place with below extension |
+ | ** ''hier'': array of place | ||
+ | * ''count'': number | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getPlacesFromText?name=Guyana&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getLocalitiesFromText ==== | ==== getLocalitiesFromText ==== | ||
Line 704: | Line 986: | ||
* ''name'': string | * ''name'': string | ||
* ''limit'': number | * ''limit'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''locs'': array of below elements |
+ | ** ''name'': string | ||
+ | ** ''id'': number | ||
+ | * ''count'': number | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getLocalitiesFromText?name=Guyana&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
==== getCollMethodsFromText ==== | ==== getCollMethodsFromText ==== | ||
Line 716: | Line 1,004: | ||
* ''name'': string | * ''name'': string | ||
* ''limit'': number | * ''limit'': number | ||
− | * '' | + | * ''format'': string |
+ | * ''key'': string | ||
+ | |||
===== Return ===== | ===== Return ===== | ||
− | * | + | * ''coll_methods'': array of below elements |
+ | ** ''name'': string | ||
+ | ** ''id'': number | ||
+ | * ''count'': number | ||
+ | |||
===== Example ===== | ===== Example ===== | ||
− | + | https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getCollMethodsFromText?name=reared&limit=10&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC | |
== Data Type Glossary == | == Data Type Glossary == | ||
Line 727: | Line 1,021: | ||
[[Category:OJ_Break API]] | [[Category:OJ_Break API]] | ||
+ | [[Category:APIs]] |
Latest revision as of 14:57, 9 July 2018
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.
The reference for version 2 of the API can be found here: OJ_Break_Version_2_API_Reference
Contents
- 1 API Information and Access
- 2 Procedural Reference
- 2.1 Agent
- 2.2 Taxon
- 2.2.1 getTaxonStats
- 2.2.2 getTaxonInfo
- 2.2.3 getTaxonHierarchy
- 2.2.4 getIncludedTaxa
- 2.2.5 getTaxonSynonyms
- 2.2.6 getLocalities
- 2.2.7 getLocalities
- 2.2.8 getCuids
- 2.2.9 getCuids
- 2.2.10 getTypes
- 2.2.11 getInsts
- 2.2.12 getTaxonLiterature (deprecated)
- 2.2.13 getTaxonLit
- 2.2.14 getAssociations
- 2.2.15 getHabitats
- 2.2.16 getTaxonMedia
- 2.2.17 getTaxonBreakdown
- 2.2.18 getTaxonPhenology
- 2.2.19 getTaxonNewTaxaByPub
- 2.2.20 getTaxonNewTaxaByYear
- 2.2.21 getTaxonStatsForYear
- 2.3 Occurrence
- 2.4 Locality
- 2.5 Place / Geopolitical Entity
- 2.6 Literature
- 2.7 Journal
- 2.8 Institution
- 2.9 Text Search
- 3 Data Type Glossary
API Information and Access
This page specifies the methods and data defined by OJ_Break Version 1. Using the OJ_Break Version 1 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: https://osuc.biosci.ohio-state.edu/cgi-bin/OJ_Break_API.py/getTaxonStats?tnuid=30148&format=json&key=FBF57A9F7A666FC0E0430100007F0CDC
To read more about using the OJ_Break Version 1 API, go to OJ_Break API Access.
Procedural Reference
Agent
getCollectorInfo
Description
Parameters
- collector_id: number
- format: string
- key: string
Return
- collector_info: array of author_info
Example
getAuthorPubs
Description
Parameters
- author_id: number
- format: string
- key: string
Return
- pubs: array of literature_extended
Example
getCollTrips2
Description
Parameters
- collector_id: number
- format: string
- key: string
Return
- coll_trips: array of collection_basic, taxon_basic, loc_coords, and collector.
Example
getAuthorTaxa
Description
Parameters
- author_id: number
- format: string
- key: string
Return
taxa: array of taxon_basic
Example
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 objectively 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
Gets information and specimen types for a specified taxon.
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 type_extended
Example
getInsts
Description
Gets institutions which hold specimens for a selected taxon.
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. Get literature for a selected taxon.
Parameters
- tnuid: number
- showSyns: boolean_flag
- format: string
- key: string
Return
- pubs: array of pub_extended
Example
getAssociations
Description
Get evolutionary relationships for a certain taxon.
Parameters
- tnuid: number
- rank_grouping: string
- format: string
- key: string
Return
- associations: array of association
Example
getHabitats
Description
Get descriptions of the habitats that a selected specimen inhabits.
Parameters
- tnuid: number
- format: string
- key: string
Return
- habitats: array of habitat
Example
getTaxonMedia
Description
Get images, videos, or sound clips of a selected taxon.
Parameters
- tnuid: number
- format: string
- key: string
Return
- media: array of media_basic
Example
getTaxonBreakdown
Description
Get count of genders and total specimen included in the current rank.
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
Get taxon specimens by date.
Parameters
- tnuid: number
- format: string
- key: string
Return
- spms: array of below elements
- date: string
- sort_date: string
- cuid: string
Example
getTaxonNewTaxaByPub
Description
Get count of new specimens for a specific taxon by publication.
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
Get count of new specimens for a specific taxon by year.
Parameters
- tnuid: number
- validOnly: string
- format: string
- key: string
Return
- years: array of below elements
- taxa_num: string
- year: string
Example
getTaxonStatsForYear
Description
Get stats, such as image count, new genera introduced, new specimen introduced, and more by year for a selected taxon.
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 Record
getSpmInfo
Description
Get info for a specific specimen occurrence.
Parameters
- cuid: string
- format: string
- key: string
Return
- spmInfo: record_vouchered
Example
getSpmsInfo
Description
Get info for multiple specimen occurrences.
Parameters
- cuids: array of string
- format: string
- key: string
Return
- spmsInfo: array of record_vouchered
Example
Unvouchered Record
getUnvoucheredRecord
Description
Get specimen record information for a selected unvouchered specimen.
Parameters
- unv_id: number
- format: string
- key: string
Return
- unvoucheredRecord: record_unvouchered
Example
getUnvoucheredRecords
Description
Get unvouchered specimen records for a selected taxon and place.
Parameters
- tnuid: number
- showChildren: string
- pnids: array of number
- format: string
- key: string
Return
- unvoucheredRecords: array of record_unvouchered
Example
Locality
getLocalityInfo
Description
Get basic information for a specific locality, including specimen occurrences, place hierarchy, and coordinates.
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
- cuids: array of record_vouchered (only present if specified) or array of cuid
- sex: array of spm_sex
Example
getUnvLocalityInfo
Description
Get locality information and occurrences (specimens) for a selected locality. The request can be narrowed down further by selected multiple parameter options.
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
- cuids: array of cuid
Example
Place / Geopolitical Entity
getPlaceInfo
Description
Get basic place information including the place hierarchy, number of specimens, and number of species.
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
Get smaller levels of divisions for a selected place.
Parameters
- place_id: number
- format: string
- key: string
Return
- subdivs: array of place
Example
getGeoTaxa
Description
Get taxonomic information from a specified place.
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
Get collecting trips info for a specified place.
Parameters
- place_id: number
- format: string
- key: string
Return
- coll_trips: array of loc_basic and collector.
Example
getGeoCollTrips2
Description
Get collecting trips and taxa info for a specified place.
Parameters
- place_id: number
- format: string
- key: string
Return
- coll_trips: array of taxon_basic, collection, collector and loc_basic with below extension
- valid_taxon: taxon_basic (only present when defined)
Example
getGeoInsts
Description
Get institutions from a selected place.
Parameters
- place_id: number
- format: string
- key: string
Return
- collections: array of collection_extended
Example
Literature
getLitReference
Description
Get the reference for a selected publication.
Parameters
- pub_id: number
- format: string
- key: string
Return
- pub_ref: literature_extended
Example
getLitParts
Description
Get parts of the selected publication, such as pages, pdf urls, chapters, titles, authors, and more.
Parameters
- pub_id: number
- format: string
- key: string
Return
- pub_parts: array of literature_extended
Example
getPubTaxonCitation
Description
Get cited taxon information from a selected publication.
Parameters
- pub_id: number
- format: string
- key: string
Return
- pub_cits: array of pub_basic and taxon_basic with below extensions
- 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
Get specimen of which the description of a new species is based.
Parameters
- inst_id: number
- format: string
- key: string
Return
- types: array of type
Example
getSecondaryTypes
Description
Get specimen that are occurrences of a specific species, but not a primary type.
Parameters
- inst_id: number
- format: string
- key: string
Return
- types: array of type
Example
getInstTaxa
Description
Get taxa and related taxonomic information from a selected institution.
Parameters
- inst_id: number
- format: string
- key: string
Return
- taxa: array of taxon_extended with below extension
- hier: taxon_hierarchy
Example
getInstCollTrips2
Description
Get collecting trip events and the specimen collected for a selected institution.
Parameters
- inst_id: number
- format: string
- key: string
Return
- coll_trips: array of taxon_basic, collection, collector, and loc_basic.
Example
getInstPubs
Description
Get published literature from a selected institution.
Parameters
- inst_id: number
- format: string
- key: string
Return
- pubs: array of literature_extended
Example
Text Search
getSearchResults
Description
Get database results from a text keyword search.
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 with below extension
- hier: array of place
- count: number
- places: array of place 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
Get taxa results from a selected search keyword.
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
Get occurrence results from a selected search keyword.
Parameters
- name: string
- limit: number
- format: string
- key: string
Return
- cuids: array of cuid
- count: number
Example
getAgentsFromText
Description
Get agent (person and/or party) results from a selected search keyword.
Parameters
- name: string
- limit: number
- includeParty: string
- format: string
- key: string
Return
- agents: array of below elements
- id: number
- type: string
- name: string
- inst: string
- count: number
Example
getInstFromText
Description
Get institution/collection results from a selected search keyword(s).
Parameters
- name: string
- limit: number
- format: string
- key: string
Return
- inst: array of collection_extended
- count: number
Example
getJournalsFromText
Description
Get journal results from a selected search keyword(s).
Parameters
- name: string
- limit: number
- format: string
- key: string
Return
- journals: array of below elements
- name: string
- id: number
- count: number
Example
getOrgsFromText
Description
Get organization results for a selected search keyword(s).
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 with below extension
- hier: array of place
- 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