- Example of query the available schema using SSBD API in JSON format:
What is SSBD API?
SSBD API is the Application Programming Interface for accessing the internal data of the SSBD database. The API is based on the web development practice of using RESTFul architecture. A RESTful API call is simply an HTTP request to the SSBD server.
Prerequisite
Before you begin, you need to be familiar with BDML file, its terminology and its schema. Please refer to BDML Specification for more information.
The latest API has simiplified the interface and does not follow the structure of BDML schema. But a familarlity of it will help in working with the API.
Summary of SSBD API (v3)
API | Request Method | Functions | Status |
---|---|---|---|
/SSBD/api/v3/ | GET | list all the available APIs | |
/SSBD/api/v3/data/ | GET | retrieve meta information | Only support BDML 3.0; |
/SSBD/api/v3/contact/ | GET | retrieve contact details | Only support BDML 3.0; |
/SSBD/api/v3/contributor/ | GET | retrieve contributors details | Only support BDML 3.0; |
/SSBD/api/v3/person/ | GET | retrieve person contact and affiliation details | Only support BDML 3.0; |
/SSBD/api/v3/affiliation/ | GET | retrieve affiliation details | Only support BDML 3.0; |
/SSBD/api/v3/bd5coords/ | GET | retrieve quantitative data | Only support BDML 3.0; |
/SSBD/api/v3/bd5scaleunit/ | GET | retrieve scaleunit data | Only support BDML 3.0; |
SSBD API Schema
There are two default formats that the API will return. It returns the data in JSON formats (XML format is depreciated).
affiliation API
- Description
- Retrieve affiliation information. Normally affiliation data are retrieved with the use of contact contributor and person api instead
Fields | Description | Usage example | Usage comment |
---|---|---|---|
E_mail | Email address of the contact person | http://ssbd.qbic.riken.jp/SSBD/api/v3/affiliation/?format=json;E_mail__icontains=riken | To retrieve Email address which contains 'riken' from SSBD |
person | Using person API to retrieve affilion | http://ssbd.qbic.riken.jp/SSBD/api/v3/affiliation/?format=json;person__last_name=OnamiTo retrieve affiliation information by searching the person's last name as 'Onami' from SSBD
| |
- affiliation Schema
- http://ssbd.qbic.riken.jp/SSBD/api/v3/affiliation/schema/?format=json
b5coords API
- Description
- It provides an interface to retrieve the quantitative numerical data. It only support BDML 3.0
Fields | Description | Usage example | Usage comment |
---|---|---|---|
bdmlID | retrieve quantitiatve data based on unique bdmlID (UUID) identity number of the BDML file stored in SSBD. It uses exact bdmlID | http://ssbd.qbic.riken.jp/SSBD/api/v3/bd5coords/?format=json;bdmlID=4ed09fa3-7650-45a9-ac55-426980aa7d0a;&ts=1;&limit=2 | To retrieve coordinates data from SSBD for bdmlID 4ed09fa3-7650-45a9-ac55-426980aa7d0a |
entity | Type of entity that the coordinates belong to, e.g. line, point, sphere, etc. | NA | cannot be searched; retrieval only |
id | entity ID. | NA | cannot be searched; retrieval only |
x | x coordinates | NA | cannot be searched; retrieval only |
y | y coordinates | NA | cannot be searched; retrieval only |
z | z coordinates. | NA | cannot be searched; retrieval only |
radius | radius of a sphere or a circle entity | NA | cannot be searched; retrieval only |
t | time values | NA | cannot be searched; retrieval only; use ts (time step) for retrieval. |
ts | time step values | http://ssbd.qbic.riken.jp/SSBD/api/v3/bd5coords/?format=json;bdmlID=4ed09fa3-7650-45a9-ac55-426980aa7d0a;&ts=1; | can be searched; |
- Example of using query to retrieve quantitative data using SSBD API in JSON:
// 20190104185349 // http://ssbd.qbic.riken.jp/SSBD/api/v3/bd5coords/?format=json;bdmlID=4ed09fa3-7650-45a9-ac55-426980aa7d0a;&ts=1;&limit=2 { "meta": { "limit": 2, "next": "/SSBD/api/v3/bd5coords/?bdmlID=4ed09fa3-7650-45a9-ac55-426980aa7d0a&offset=2&limit=2&ts=1&format=json", "offset": 0, "previous": null, "total_count": 10936 }, "objects": [ { "entity": "line", "id": "2000", "label": "P0", "radius": null, "sid": 0, "t": "2", "x": "266", "y": "306", "z": "15" }, { "entity": "line", "id": "2000", "label": "P0", "radius": null, "sid": 0, "t": "2", "x": "265", "y": "307", "z": "15" } ] }
b5scaleunit API
- Description
- It provides an interface to retrieve the scale unit quantitative numerical data. It only support BDML 3.0
Fields | Description | Usage example | Usage comment |
---|---|---|---|
bdmlID | retrieve scaleunit data based on unique bdmlID (UUID) identity number of the BDML file stored in SSBD. It uses exact bdmlID | http://ssbd.qbic.riken.jp/SSBD/api/v3/bd5scaleunit/?format=json;bdmlID=4ed09fa3-7650-45a9-ac55-426980aa7d0a | To retrieve scaleunit data from SSBD for bdmlID 4ed09fa3-7650-45a9-ac55-426980aa7d0a |
dimension | Dimension of the quantiative numerical data. Possible dimension: 3D+T, 2D+T, 1D+T, 3D, 2D, 1D | NA | cannot be searched; retrieval only |
xScale | scale of x coordinates | NA | cannot be searched; retrieval only |
yScale | scale y coordinates | NA | cannot be searched; retrieval only |
zScale | scale z coordinates. | NA | cannot be searched; retrieval only |
sUnit | scale unit | NA | cannot be searched; retrieval only |
tScale | scale of time | NA | cannot be searched; retrieval only |
tUnit | time unit | NA | cannot be searched; retrieval only |
- Example of using query to retrieve scaleUnit quantitative data using SSBD API in JSON:
// 20190106144156 // http://ssbd.qbic.riken.jp/SSBD/api/v3/bd5scaleunit/?format=json;bdmlID=4ed09fa3-7650-45a9-ac55-426980aa7d0a;&ts=1;&limit=2 { "meta": { "limit": 2, "next": null, "offset": 0, "previous": null, "total_count": 1 }, "objects": [ { "dimension": "3D+T", "sUnit": "micrometer", "tScale": "40.0", "tUnit": "second", "xScale": "0.105", "yScale": "0.105", "zScale": "0.5" } ] }
contact API
- Description
- Contact information It is normally used together with data, person and affiliation API
Fields | Description | Usage example | Usage comment |
---|---|---|---|
data | meta data stored in SSBD | http://ssbd.qbic.riken.jp/SSBD/api/v3/contact/?format=json;data__localID__icontains=wt(N2)07 | To retrieve Contact data from SSBD for data's localID which contains 'wt(N2)07' |
person | person associated with the data. | http://ssbd.qbic.riken.jp/SSBD/api/v3/contact/?format=json;person__last_name=Okada | To retrieve Contact data from SSBD for person with the last name Okada |
affiliation | affiliation associated with the data. | http://ssbd.qbic.riken.jp/SSBD/api/v3/contact/?format=json;affiliation__E_mail__icontains=keller | To retrieve Contact information from SSBD with affiliation's email address containing the phrase 'keller' |
- Contact Schema
-
http://ssbd.qbic.riken.jp/SSBD/api/v3/contact/schema/?format=json
contributor API
- Description
- Contributor information It is normally used together with data, person and affiliation API
Fields Description Usage example Usage comment data meta data stored in SSBD http://ssbd.qbic.riken.jp/SSBD/api/v3/contributor/?format=json;data__localID__icontains=wt(N2)07 To retrieve Contributor data from SSBD for data's localID which contains 'wt(N2)07' person person associated with the data. http://ssbd.qbic.riken.jp/SSBD/api/v3/contributor/?format=json;person__last_name=Keller To retrieve Contributor from SSBD for person with the last name Keller affiliation affiliation associated with the data. http://ssbd.qbic.riken.jp/SSBD/api/v3/contributor/?format=json;affiliation__E_mail__icontains=kyoda To retrieve Contributor information from SSBD with affiliation's email address containing the phrase 'kyoda' - Contact Schema
-
http://ssbd.qbic.riken.jp/SSBD/api/v3/contributor/schema/?format=json
data API
- Description
- Retrieve meta information of the data stored in SSBD.
Fields Description Usage example Usage comment bdmlID Retrieve data based on unique BDMLID http://ssbd.qbic.riken.jp/SSBD/api/v3/data/?format=json;bdmlID__icontains=32 To retrieve summary data from SSBD for bdmlID that matches or contains the phrase "32" localID Retreive data based on internal or local identifier http://ssbd.qbic.riken.jp/SSBD/api/v3/data/?format=json;localID__icontains=wt(N2)07 To retrieve all the meta data from SSBD when localID contains the phrase "wt(N2)07". Note that the field is changed from previous bdml_ID to bdmlUUID in the new API. organism Retrieve data based on organism http://ssbd.qbic.riken.jp/SSBD/api/v3/data/?format=json;organism__icontains=rerio Return data with organism name containing the phrase "rerio". - Example of response
-
- Trying to retrieve meta data from SSBD for bdmlID "320e02ee-1c6c-4e03-a6da-75b5c413b6a3"
- output format is in JSON format
- http://ssbd.qbic.riken.jp/SSBD/api/v3/data/?format=json;bdmlID=320e02ee-1c6c-4e03-a6da-75b5c413b6a3
/ 20190104193200 // http://ssbd.qbic.riken.jp/SSBD/api/v3/data/?format=json;bdmlID=320e02ee-1c6c-4e03-a6da-75b5c413b6a3 { "meta": { "limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 1 }, "objects": [ { "PMID": "18845710", "SID": 5, "basedon": "Experiment", "bdmlID": "320e02ee-1c6c-4e03-a6da-75b5c413b6a3", "citation": null, "contributors": "Philipp Keller, Annette Schmidt, Joachim Wittbrodt, Ernst Stelzer", "datatype": "nuclear positions", "dblink": "http://www.embl.de/digitalembryo/fish.html", "description": "in toto reconstruction of zebrafish MZoep mutant development", "gene": null, "license": "CC BY-NC-SA", "localID": "zebrafish_in_toto_mzoep.mat", "method_summary": "See details in Keller et al. (2008) Science 322, 1065-1069.", "orf": null, "organism": "D. rerio", "release": "2017-12-20", "schema_ver": "3.000", "title": "BDML file for in toto reconstruction of zebrafish MZoep mutant development" }
- http://ssbd.qbic.riken.jp/SSBD/api/v3/data/?format=json;bdmlID=320e02ee-1c6c-4e03-a6da-75b5c413b6a3
ontology API
- Description
- Retrieve ontology information of the data stored in SSBD.
Fields | Description | Usage example | Usage comment |
---|---|---|---|
ID | Retrieve ontology data based on ID | http://ssbd.qbic.riken.jp/SSBD/api/v3/ontology/?format=json;ID__icontains=002;data__bdmlID=4ed09fa3-7650-45a9-ac55-426980aa7d0a | To retrieve ontology data from SSBD for bdmlID that matches 4ed09fa3-7650-45a9-ac55-426980aa7d0a and contains ID "002" |
data | Retrieve ontology data based on meta data stored in SSBD | http://ssbd.qbic.riken.jp/SSBD/api/v3/ontology/?format=json;data__localID__icontains=wt(N2)07 | To retrieve Contributor data from SSBD for data's localID which contains 'wt(N2)07' |
ontologyID | Retreive ontology data based on ontologyID | http://ssbd.qbic.riken.jp/SSBD/api/v3/ontology/?format=json;ontologyID__icontains=6239 | To retrieve all the ontology data from SSBD when ontologyID contains the phrase "6239". |
ontologyResource | Retrieve ontology data based on ontologyResource | NA | Return ontology resource name. |
ontologyURI | Retrieve ontology URI | http://ssbd.qbic.riken.jp/SSBD/api/v3/ontology/?format=json;ontologyURI__icontains=obo | Return ontology data with onoloty URI containing the phrase "obo". |
term | Retrieve ontology data based on ontology term | http://ssbd.qbic.riken.jp/SSBD/api/v3/ontology/?format=json;term__icontains=elegan | Return ontology data with term containing the phrase "elegan". |
- Example of response
-
- Trying to retrieve ontology data from SSBD for bdmlID "320e02ee-1c6c-4e03-a6da-75b5c413b6a3"
- output format is in JSON format
- http://ssbd.qbic.riken.jp/SSBD/api/v3/ontology/?format=json;data__bdmlID=4ed09fa3-7650-45a9-ac55-426980aa7d0a
// 20190106150352 // http://ssbd.qbic.riken.jp/SSBD/api/v3/ontology/?format=json;data__bdmlID=4ed09fa3-7650-45a9-ac55-426980aa7d0a { "meta": { "limit": 20, "next": null, "offset": 0, "previous": null, "total_count": 2 }, "objects": [ { "ID": "001", "data": { "PMID": "23172286", "SID": 2, "basedon": "Experiment", "bdmlID": "4ed09fa3-7650-45a9-ac55-426980aa7d0a", "citation": null, "contributors": "Koji Kyoda, Mari Furukawa, Ryoko Arai, Shuichi Onami", "datatype": "nuclear division dynamics", "dblink": "http://so.qbic.riken.jp/wddd/", "description": "quantitative information about nuclear division dynamics in B0336.10(RNAi) embryo (rpl-23(RNAi) embryo)", "gene": null, "license": "CC BY-SA", "localID": "B0336.10(gPCR)040518_01", "method_summary": "See details in Kyoda et al. (2013) Nucleic Acids Res 41, D732-D737.", "orf": null, "organism": "C. elegans", "release": "2017-12-20", "schema_ver": "3.000", "title": "BDML file for quantitative information about nuclear division dynamics of B0336.10(RNAi) embryo" }, "ontologyID": "GO_0009790", "ontologyResource": null, "ontologyURI": "http://purl.obolibrary.org/obo/", "term": "embryo development" }, { "ID": "002", "data": { "PMID": "23172286", "SID": 2, "basedon": "Experiment", "bdmlID": "4ed09fa3-7650-45a9-ac55-426980aa7d0a", "citation": null, "contributors": "Koji Kyoda, Mari Furukawa, Ryoko Arai, Shuichi Onami", "datatype": "nuclear division dynamics", "dblink": "http://so.qbic.riken.jp/wddd/", "description": "quantitative information about nuclear division dynamics in B0336.10(RNAi) embryo (rpl-23(RNAi) embryo)", "gene": null, "license": "CC BY-SA", "localID": "B0336.10(gPCR)040518_01", "method_summary": "See details in Kyoda et al. (2013) Nucleic Acids Res 41, D732-D737.", "orf": null, "organism": "C. elegans", "release": "2017-12-20", "schema_ver": "3.000", "title": "BDML file for quantitative information about nuclear division dynamics of B0336.10(RNAi) embryo" }, "ontologyID": "NCBITaxon_6239", "ontologyResource": null, "ontologyURI": "http://purl.obolibrary.org/obo/", "term": "C. elegans" } ] }
- http://ssbd.qbic.riken.jp/SSBD/api/v3/ontology/?format=json;data__bdmlID=4ed09fa3-7650-45a9-ac55-426980aa7d0a