Loading…
Loading…
The African DSI DataBank is a federated catalog of African-origin biodiversity/agriculture Digital Sequence Information — genomes, proteins, predicted structures, eDNA/metagenomic classifications, and field/specimen/cellular imaging metadata, aggregated from Sub-regional, National, and Spoke nodes across the continent. Every endpoint below is real and live; the interactive, always-current reference is the OpenAPI schema itself: /api/docs ↗.
Every record carries one of four access tiers, enforced before any byte is served — see Terms of use for the full explanation.
public — no authentication needed.regional_researcher — requires an approved access request; may involve a third-party ABS identity check.restricted — requires an approved access request; never auto-approved.embargoed — like restricted or regional_researcher until its release date, then public automatically.Public reads need no token. For anything else, a script sends an Authorization: Bearer <token> header with one of two kinds of token:
adsi_, needs no password or sign-in code, and lasts up to a year. It is read-only: it reads and downloads what your account may (including records your approved access requests open), but can't change anything or use any role.POST /api/v1/accounts/login, valid for an hour, for changes such as submitting an access request. An account with two-step sign-in also sends the code from its app.curl -H "Authorization: Bearer adsi_..." "https://hub.africandsidatabank.africa/api/v1/access/requests"
An approved contributor can tick Can submit when making a token, after entering their password and code once more. That token also sends submissions in your name: the submission forms (POST /api/v1/proteins/submissions and the others), genome and transcriptome submissions (/api/v1/sequence-submissions), hosted data (/api/v1/hosted-data) and large-file uploads (/api/v1/large-files/uploads). It can't do anything else: setting a record's tier, deciding access requests, ENA consent, moving records and account changes all still need you to log in. If you stop being a contributor, it stops working at once. Each submission it sends is listed on your account page. Never store your authenticator app's secret in a script: use a token instead.
curl -X POST -H "Authorization: Bearer adsi_..." -H "Content-Type: application/json" \ -d @protein.json "https://hub.africandsidatabank.africa/api/v1/proteins/submissions"
Each personal API token may make 60 requests a minute and 10,000 a day; beyond that the answer is 429 Too Many Requests, so wait and try again. Please keep unauthenticated scripts to a similar pace, and use the bulk exports below rather than paging through every record.
The public API reference lists every endpoint anyone may call without a login (also as an OpenAPI file, public-api.json, to load into your own tools). The full reference, including endpoints only node software and administrators use, is at /api/docs ↗.
curl "https://hub.africandsidatabank.africa/api/v1/catalog/species?q=Loxodonta"
curl "https://hub.africandsidatabank.africa/api/v1/catalog/sequences"
curl "https://hub.africandsidatabank.africa/api/v1/catalog/sequences/{id}/file"curl "https://hub.africandsidatabank.africa/api/v1/proteins"
curl "https://hub.africandsidatabank.africa/api/v1/structures"
curl "https://hub.africandsidatabank.africa/api/v1/edna/sites"
curl "https://hub.africandsidatabank.africa/api/v1/metagenomics/sites"
curl "https://hub.africandsidatabank.africa/api/v1/identifiers/AFDSI-SEQ-1042"
curl "https://hub.africandsidatabank.africa/api/v1/federation/contributions"
Two public, unauthenticated feeds for external harvesting/discovery tooling — neither needs an account, and both are hard-scoped to public-tier records only.
A standard Darwin Core Archive ZIP (meta.xml + an occurrence-core data table + eml.xml) — the format GBIF's own IPT/harvesting pipeline consumes. Scoped to genomes only, since Darwin Core's Occurrence core is specimen/collection- event-shaped and only genomes carry that data in this catalog.
curl "https://hub.africandsidatabank.africa/api/v1/export/darwin-core.zip"
A JSON-LD dcat:Catalog document listing every dataset this Hub holds (all 7 citable entity types) with record counts and links to each dataset's own list endpoint — the machine-readable "what does this Hub have" document a national or regional open-data portal can index.
curl "https://hub.africandsidatabank.africa/api/v1/export/dcat"
import requests
BASE = "https://hub.africandsidatabank.africa"
# Search the species catalog — no auth needed for public data.
# List endpoints are paginated: {"items": [...], "count": N}.
response = requests.get(f"{BASE}/api/v1/catalog/species", params={"q": "Loxodonta"})
response.raise_for_status()
for species in response.json()["items"]:
print(species["scientific_name"], species["common_name"])
# Anything beyond public-tier data: a personal API token from your account
# page (read-only), kept out of the script itself.
import os
headers = {"Authorization": f"Bearer {os.environ['DATABANK_TOKEN']}"}
mine = requests.get(f"{BASE}/api/v1/access/requests", headers=headers)
mine.raise_for_status()
for request in mine.json()["items"]:
print(request["id"], request["decision"])# install.packages(c("httr2", "jsonlite"))
library(httr2)
base <- "https://hub.africandsidatabank.africa"
# Search the species catalog: public, no token.
species <- request(base) |>
req_url_path_append("api", "v1", "catalog", "species") |>
req_url_query(q = "Loxodonta") |>
req_perform() |>
resp_body_json()
for (s in species$items) cat(s$scientific_name, "
")
# With your personal API token (set DATABANK_TOKEN in ~/.Renviron).
# req_retry waits and tries again when the rate limit answers 429.
mine <- request(base) |>
req_url_path_append("api", "v1", "access", "requests") |>
req_auth_bearer_token(Sys.getenv("DATABANK_TOKEN")) |>
req_retry(max_tries = 3) |>
req_perform() |>
resp_body_json()
# Download a file your account may read.
request(base) |>
req_url_path_append("api", "v1", "catalog", "sequences", "42", "file") |>
req_auth_bearer_token(Sys.getenv("DATABANK_TOKEN")) |>
req_perform(path = "genome-42.fasta")The short snippet above shows individual calls in isolation. This complete, runnable script (also in the repository at docs/examples/researcher_workflow_example.py) composes them into the real end-to-end flow a researcher actually needs: search the catalog, find a genome record, and either download it directly (public-tier) or submit a real access request and check on its status (anything else). Worth knowing before reading it: submitting an access request needs a login (the request is made by that account, and only that account may download once it is approved), and a personal API token can't submit one because tokens are read-only; it can check the request's status and download afterwards. Run it with python researcher_workflow_example.py "Species name" — only dependency is pip install requests.
import os
import sys
import requests
BASE_URL = os.environ.get("HUB_BASE_URL", "https://hub.africandsidatabank.africa")
USERNAME = os.environ.get("HUB_USERNAME", "")
PASSWORD = os.environ.get("HUB_PASSWORD", "")
def log(message):
print(f"\n>>> {message}")
# Step 1: search the species catalog — no auth needed, ever. List
# endpoints are paginated: {"items": [...], "count": N}.
def find_species(scientific_name):
log(f"Searching the species catalog for '{scientific_name}'...")
response = requests.get(
f"{BASE_URL}/api/v1/catalog/species", params={"q": scientific_name}, timeout=30
)
response.raise_for_status()
matches = response.json()["items"]
if not matches:
raise SystemExit(f"No species matched '{scientific_name}'.")
species = matches[0]
print(f"Found: {species['scientific_name']} (species id {species['id']})")
return species
# Step 2: find a genome record for that species — also public.
def find_genome_record(species_id):
log(f"Looking up sequence records for species id {species_id}...")
response = requests.get(
f"{BASE_URL}/api/v1/catalog/sequences",
params={"species_id": species_id, "sequence_type": "genome"},
timeout=30,
)
response.raise_for_status()
records = response.json()["items"]
if not records:
print("No genome-type sequence record exists for this species yet.")
return None
record = records[0]
print(
f"Found sequence record {record['id']} "
f"(access_tier={record['access_tier']!r}, citable_id={record['citable_id']!r})"
)
return record
# Step 3a: the public-tier path — download directly, no auth.
def download_genome(sequence_record_id, out_path, headers=None):
log(f"Downloading assembly file for sequence record {sequence_record_id}...")
response = requests.get(
f"{BASE_URL}/api/v1/catalog/sequences/{sequence_record_id}/file",
headers=headers or {},
timeout=120,
)
response.raise_for_status()
with open(out_path, "wb") as handle:
handle.write(response.content)
print(f"Saved {len(response.content):,} bytes to {out_path}")
# Step 3b: the gated path — submitting a request, checking its status and
# any actual download all need a bearer token. The request is made by the
# logged-in account, and an approval lets exactly that account download.
def request_access(sequence_record_id, headers):
log(f"Submitting an access request for sequence record {sequence_record_id}...")
response = requests.post(
f"{BASE_URL}/api/v1/access/requests",
json={
"sequence_record_id": sequence_record_id,
"purpose": "Worked-example script: evaluating this genome for a comparative study.",
},
headers=headers,
timeout=30,
)
response.raise_for_status()
request = response.json()
print(
f"Access request #{request['id']} submitted — status: {request['decision']!r}. "
"A Continental Admin needs to approve this before the file can be downloaded."
)
return request
def login(username, password):
log(f"Logging in as {username!r}...")
response = requests.post(
f"{BASE_URL}/api/v1/accounts/login",
json={"username": username, "password": password},
timeout=30,
)
response.raise_for_status()
return response.json()["access_token"]
def check_access_request_status(request_id, headers):
log(f"Checking status of access request #{request_id}...")
response = requests.get(
f"{BASE_URL}/api/v1/access/requests/{request_id}", headers=headers, timeout=30
)
response.raise_for_status()
decision = response.json()["decision"]
print(f"Access request #{request_id} is currently: {decision!r}")
return decision
# GET /requests, logged in, already returns only your own requests — this
# keeps the script safe to re-run instead of piling up duplicate requests.
def find_own_request_for_record(sequence_record_id, headers):
response = requests.get(f"{BASE_URL}/api/v1/access/requests", headers=headers, timeout=30)
response.raise_for_status()
for existing in response.json()["items"]:
if existing["sequence_record_id"] == sequence_record_id:
return existing
return None
def main():
scientific_name = sys.argv[1] if len(sys.argv) > 1 else "Loxodonta africana"
species = find_species(scientific_name)
record = find_genome_record(species["id"])
if record is None:
return
out_path = f"{record['citable_id'] or record['id']}.fasta"
if record["access_tier"] == "public":
download_genome(record["id"], out_path)
return
print(
f"\nThis record is '{record['access_tier']}'-tier, not public — a download needs an "
"approved access request first."
)
if not USERNAME or not PASSWORD:
print(
"No HUB_USERNAME/HUB_PASSWORD set — sign up for an account (see /signup), then "
"re-run this script with both set to submit an access request under your account."
)
return
token = login(USERNAME, PASSWORD)
headers = {"Authorization": f"Bearer {token}"}
request = find_own_request_for_record(record["id"], headers)
if request is None:
request = request_access(record["id"], headers)
status = request["decision"]
if status != "approved":
status = check_access_request_status(request["id"], headers)
if status == "approved":
download_genome(record["id"], out_path, headers=headers)
else:
print(
"\nNot approved yet. Re-run this script once a Continental Admin approves it — "
"the download will then proceed automatically."
)
if __name__ == "__main__":
main()