API Reference

All endpoints below are under /api/. Upload endpoints require a token; everything else (downloads, search, browsing) is public.

Authentication

Add this header to any upload request:

Authorization: Token <your-token-here>

Generate a token for your account with uv run python manage.py drf_create_token <username>.

Uploading

# Gazetteer (GeoJSON)
curl -X POST http://127.0.0.1:8000/api/gazetteer/upload/ \
  -H "Authorization: Token <token>" \
  -F "file=@gazetteer.geojson"

# Location aliases (CSV)
curl -X POST http://127.0.0.1:8000/api/gazetteer/aliases/upload/ \
  -H "Authorization: Token <token>" \
  -F "file=@location_aliases.csv"

# Dataset (safedata_validator JSON export)
curl -X POST http://127.0.0.1:8000/api/datasets/upload/ \
  -H "Authorization: Token <token>" \
  -F "file=@dataset.json"

Re-uploading a dataset with a zenodo_record_id that already exists updates that dataset in place (treated as a correction) rather than creating a duplicate. Uploads are all-or-nothing: if any part of a file fails, nothing from it is saved.

Downloading

No authentication required.

Downstream tools should check the hash endpoint before re-downloading a file, to avoid unnecessary transfers.

Searching datasets

Six search endpoints, matching the query types supported by the safedata R package. All accept GET requests with query parameters, and all support two shared parameters:

• ids — restrict results to a specific set of zenodo_record_ids (repeatable: ?ids=1&ids=2). This is how searches can be chained together (an "AND"-like combination).
• most_recent — restrict results to only the latest version of each dataset (presence alone means true: ?most_recent).

Combining an "OR" across two searches is done by the client — issue two searches and union the results; combining an "AND" is done by restricting the second search's ids to the first search's result set.

Record metadata and taxonomy