The SAFE Database API

We maintain a database of research data collected at the SAFE Project. Datasets submitted to SAFE are validated and then published through our community page at the Zenodo data repository. The basic summary metadata is provided here and on the Zenodo records and is searchable through Zenodo and other data indexing sites, but we also provide an API providing finer level dataset indexing.

The root URL for the API is shown below - the bare URL redirects to this API description.

https://www.safeproject.net/api

Shared query parameters

In addition to their own query parameters, the endpoints described below also accept the following global options:

most_recent

Adding this flag to the query string will restrict the API to returning only the most recent version of a dataset.

https://www.safeproject.net/api/search/taxa?most_recent=&name=Formicidae

ids

This option allows the user to restrict the search to particular dataset records, using zenodo_record_id values, allowing API calls to refine previous searches.

https://www.safeproject.net/api/search/taxa?ids=1198302&ids=1995439&name=Formicidae

Record endpoint

This endpoint returns the metadata for the Zenodo record ID provided. This is exactly the same as the information set out in the Zenodo dataset description as JSON data. This endpoint ignores the shared ids or most_recent query parameters. The JSON data is complex!

https://www.safeproject.net/api/record/1198302

Files endpoint

The files endpoint returns the files associated with datasets. There will often only be a single Excel file, but external data files will also be listed. This endpoint does accept the shared ids or most_recent query parameters. The download link is only functional when a dataset is open access or if the listed embargo date has passed.

https://www.safeproject.net/api/files?most_recent=

{
	"count": 57,
	"entries": [
		{
			"checksum": "07df68c42b756330ed584711d74129c0",
			"filename": "template_Heon.xlsx",
			"most_recent": true,
			"zenodo_record_id": 1304117,
			"download_link": "https://zenodo.org/api/files/9df99ec9-8bc5-42b8-a8da-a695da875f32/template_Heon.xlsx",
			"dataset_access": "open",
			"zenodo_concept_id": 1198568,
			"dataset_embargo": null,
			"dataset_title": "Do logging roads impede small mammal movement in Borneo's tropical rainforests?",
			"filesize": 364916
		},
		...
	]
}

Locations_bbox endpoint

The locations_bbox endpoint provides JSON data used to validate location data provided in SAFE data format files. It returns a dictionary of containing both valid locations with their bounding boxs and a mapping of known aliases to their valid location names:

https://www.safeproject.net/api/locations_bbox

{
	"locations": {
		"RT_60M_C_160": [117.55032, 117.55032, 4.729569, 4.729569],
		"F1-1-18": [117.5409668, 117.5409668, 4.6940337, 4.6940337],
		...
	},
	"aliases": {
		"507": "OP2_507",
		"818": "F_818",
		...
	}
}

Taxa endpoint

The taxa endpoint provides JSON data on the taxon names currently used in SAFE datasets. The response is a list of taxon details, including a count of the number of datasets recording each taxon:

https://www.safeproject.net/api/taxa

[
	{
		"n_datasets": 1,
		"gbif_id": -1,
		"taxon_rank": "morphospecies",
		"taxon_name": "Leptogenys sp. 68",
		"gbif_status": "user",
		"gbif_parent_id": 1321215
	},
	{
		"n_datasets": 1,
		"gbif_id": -1,
		"taxon_rank": "morphospecies",
		"taxon_name": "Plat1",
		"gbif_status": "user",
		"gbif_parent_id": 1040352
	},
	...
]

Dataset search endpoints

We provide a number of search endpoints to locate datasets, which are described below along with their query options. All return JSON data in the same format, shown below with an example call.

https://www.safeproject.net/api/search/taxa?name=Formicidae

{
	"count": 8,
	"entries": [
		{
			"zenodo_concept_id": 1198301,
			"zenodo_record_id": 1198302,
			"dataset_title": "The role of competition in structuring ant community composition across a tropical forest disturbance gradient"
		},
		...
	]
}

The datasets all have a unique zenodo record id (zenodo_record_id), but different versions of the same dataset are all grouped together under the a concept id (zenodo_concept_id).

dates

Search for datasets by temporal extent

Examples:
    /api/search/dates?date=2014-06-12
    /api/search/dates?date=2014-06-12,2015-06-12
    /api/search/dates?date=2014-06-12,2015-06-12&match_type=contains
    /api/search/dates?date=2014-06-12,2015-06-12&match_type=within

Args:
    date (str): A string containing one or two (comma separated) dates in ISO format (2019-06-12)
    match_type (str): One of 'intersect', 'contain' and 'within' to match the provided dates to
        the temporal extents of datasets. The 'contain' option returns datasets that span a date 
        range and 'within' returns datasets that fall within that date range.

fields

Search for datasets by data field information

Examples:
    /api/search/fields?text=temperature
    /api/search/fields?ftype=numeric
    /api/search/fields?text=temperature&ftype=numeric

Args:
    text (str): A string to look for within the field name and description.
    ftype (str): A field type to match.

authors

Search for datasets by author name

Examples:
    /api/search/authors?name=Wilk

Args:
    name (str): An author name or part of a name

taxa

Search for datasets by taxon information

Examples:
    /api/search/taxa?name=Formicidae
    /api/search/taxa?gbif_id=4342
    /api/search/taxa?rank=Family

Args:
    gbif_id (int): A GBIF taxon id.
    name (str): A scientific name
    rank (str): A taxonomic rank. Note that GBIF only provides 
        kingdom, phylum, order, class, family, genus and species.

text

Search for datasets by free text search

Examples:
    /api/search/text?text=humus

Args:
    text (str): A string to look within dataset, worksheet and field 
    descriptions and titles and in dataset keywords.

spatial

Spatial search for sampling locations.

This endpoint can search for datasets using either a user-provided geometry or the geometry
of a named location from the SAFE gazetteer. The sampling locations provided in each dataset 
are tested to see if they intersect the search geometry and a buffer distance can also be 
provided to search around the query geometry.

Note that this endpoint will not retrieve datasets that have not provided sampling locations
or use new locations that are missing coordinate information. The bounding box endpoint
uses the dataset geographic extent, which is provided for all datasets.

Examples:
    /api/search/spatial?location=A_1    
    /api/search/spatial?location=A_1&distance=50    
    /api/search/spatial?wkt=Point(116.5 4.75)
    /api/search/spatial?wkt=Point(116.5 4.75)&distance=50000
    /api/search/spatial?wkt=Polygon((110 0, 110 10,120 10,120 0,110 0))

Args:
    wkt (str): A well-known text geometry. This is assumed to use latitude and longitude
        coordinates in WGS84 (EPSG:4326).
    location (str): A location name used to select a query geometry from the SAFE gazetteer.
    distance (float): A search distance in metres. All geometries are converted to the
        UTM 50N projection to provide appopriate distance searching.

locations

Search for datasets with data at a named location

Examples:
    /api/search/location?name=A_1

Args:
    name (str): A location name

bbox

Spatial search for dataset bounding boxes

The endpoint can search for datasets using either a user-provided geometry or a location
name from the SAFE gazetteer. This endpoint uses only the dataset bounding box, which is
provided for all datasets, rather than sampling location information which may not be 
recorded for some datasets.

Examples:
    /api/search/bbox?wkt=Polygon((110 0, 110 10,120 10,120 0,110 0))
    /api/search/bbox?wkt=Polygon((116 4.5,116 5,117 5,117 4.5,116 4.5))
    /api/search/bbox?wkt=Polygon((116 4.5,116 5,117 5,117 4.5,116 4.5))&match_type=contain
    /api/search/bbox?wkt=Point(116.5 4.75)&match_type=within

Args:
    wkt (str): A well-known text geometry. This is assumed to use latitude and longitude
        coordinates in WGS84 (EPSG:4326).
    location (str): A location name used to select a query geometry from the SAFE gazetteer.
    match_type (str): One of 'intersect', 'contain' and 'within' to match the provided geometry
        to the geographic extents of datasets. The 'contain' option returns datasets that 
        completely cover the query geometry and 'within' returns datasets that fall entirely
        within the query geometry.