SBDG API documentation

There are several API endpoints available for querying the SBDG. This API is in development, and so it may change - and if you have suggestions (or are interested in an API we don’t currently provide), please feel free to let us know at data@sbgrid.org.

When the SBDB is performing frontend maintance, API calls will return HTTP ERROR code 503 - automated queries should be adapted to handle this by either failing gracefully or retrying.

Listing datasets

Return lists of datasets matching specified criteria.

List published datasets

endpoint: api/list_datasets

query parameters: none

returns: JSON-encoded list of numeric dataset identifiers

List datasets of particular type

endpoint: api/meta/has_resource_type

query parameters: resourceType , plus-encoded and currently case-sensitive.

returns: JSON-encoded list of numeric dataset identifiers, or an empty list.

example: curl https://data.sbgrid.org/api/meta/has_resource_type?resourceType=X-Ray+Diffraction

List datasets with particular detector type

endpoint: api/meta/has_detector_type

query parameters: detectorType, values for detectorType are case-insensitive.

returns: JSON-encoded list of numeric dataset identifiers, or an empty list.

example: curl https://data.sbgrid.org/api/meta/has_detector_type?detectorType=pilatus

Results are for datasets known and identified as having a particular detector type. An empty result can be due to: no public datasets matching the detector type, or the extraction process not looking for that particular format. This information is a combination of information extracted from image headers and mosflm output during reprocessing.

In short - if this API behaves in ways that are unexpected, please let us know at data@sbgrid.org.

List datasets with particular image file format

endpoint: api/meta/has_detector_type

query parameters: imageFormat, values for imageFormat are case-insensitive.

returns: JSON-encoded list of numeric dataset identifiers, or an empty list.

example: curl https://data.sbgrid.org/api/meta/has_image_format?imageFormat=smv

List datasets with particular image file format

endpoint: api/meta/has_detector_manufacturer

query parameters: detectorManufacturer, values for detectorManufacturer are case-insensitive.

returns: JSON-encoded list of numeric dataset identifiers, or an empty list.

example: curl https://data.sbgrid.org/api/meta/has_detector_manufacturer?detectorManufacturer=adsc

List unique values for (some) metadata items

endpoint: api/meta/unique

query parameters: q, currently valid values are detectorType, imageFormat and detectorManufacturer

returns: JSON-encoded list of strings of unique values for the respective query, or an empty list.

example: curl https://data.sbgrid.org/api/meta/unique?q=imageFormat

Data Citation

bibtex

endpoint: api/bibtex

query parameters: dataset , numeric dataset identifier

returns: bibtex formatted data citation, or no citation available

example: curl https://data.sbgrid.org/api/bibtex?dataset=1

DATS JSON

endpoint: api/dats

query parameters: dataset , numeric dataset identifier

returns: Preliminary implementation of DATS v2.0 (encoded as JSON), or empty list.

example: curl https://data.sbgrid.org/api/dats?dataset=1