Registry API

version v1

Introduction

Quick links

This API works against the GBIF Registry, which makes all registered Datasets, Installations, Organizations, Nodes, and Networks discoverable.

Internally we use a Java web service client for the consumption of these HTTP-based, RESTful web services. It may be of interest to those coding against the API, and can be found in the registry-ws-client project.

Please note the old Registry API is still supported, but is now deprecated. Anyone starting new work is strongly encouraged to use the new API.

Datasets

The dataset API provides CRUD and discovery services for datasets. Its most prominent use on the GBIF portal is to drive the dataset search and dataset pages.

Please note deletion of datasets is logical, meaning dataset entries remain registered forever and only get a deleted timestamp. On the other hand, deletion of a dataset's contacts, endpoints, identifiers, tags, machine tags, comments, and metadata descriptions is physical, meaning the entries are permanently removed.

Resource URL Method Response Description Auth Paging Parameters
/dataset GET Dataset List Lists all datasets false true q, country, type, identifier, identifierType
/dataset POST UUID Creates a new dataset true false
/dataset/{UUID} GET Dataset Gets details for the single dataset false false
/dataset/{UUID} PUT Updates the dataset true false
/dataset/{UUID} DELETE Deletes the dataset. The dataset entry gets a deleted timestamp but remains registered. true false
/dataset/{UUID}/contact GET Contact List Lists all contacts for the dataset false false
/dataset/{UUID}/contact POST ID Create and add a dataset contact true false
/dataset/{UUID}/contact/{ID} DELETE Deletes a dataset contact with contact identifier {ID} true false
/dataset/{UUID}/contact/{ID} PUT Updates a dataset contact with contact identifier {ID} true false
/dataset/{UUID}/endpoint GET Endpoint List Lists the dataset endpoints false false
/dataset/{UUID}/endpoint POST ID Creates a dataset endpoint true false
/dataset/{UUID}/endpoint/{ID} DELETE Deletes a dataset endpoint with identifier {ID} true false
/dataset/{UUID}/identifier GET Identifier List Lists the dataset's identifiers false false
/dataset/{UUID}/identifier POST ID Creates a new dataset identifier true false
/dataset/{UUID}/identifier/{ID} DELETE Deletes a dataset's identifier with identifier {ID}> true false
/dataset/{UUID}/tag GET Tag List Lists all tags for a dataset false false
/dataset/{UUID}/tag POST ID Create and add a dataset tag true false
/dataset/{UUID}/tag/{ID} DELETE Deletes the dataset tag with tag identifier {ID} true false
/dataset/{UUID}/machineTag GET Machine Tag List Lists all machine tags for a dataset false false
/dataset/{UUID}/machineTag POST ID Create and add a dataset machine tag true false
/dataset/{UUID}/machineTag/{ID} DELETE Deletes the dataset machine tag with machine tag identifier {ID} false false
/dataset/{UUID}/comment GET Comment List Lists all comments for a dataset false false
/dataset/{UUID}/comment POST ID Create and add a dataset comment true false
/dataset/{UUID}/comment DELETE Deletes the dataset comment with comment identifier {ID} true false
/dataset/{UUID}/constituents GET Lists the dataset's subdataset constituents (datasets that have a parentDatasetKey equal to the one requested) false true
/dataset/{UUID}/document GET Metadata Document Gets a GBIF generated EML document overlaying GBIF information with any existing metadata document data. false false
/dataset/{UUID}/document POST ID Pushes a new original source metadata document for a dataset into the registry, replacing any previously existing document of the same type. true false
/dataset/{UUID}/metadata GET Metadata Description List Lists all metadata descriptions available for a dataset and optionally filters them by document type. The list is sorted by priority with the first result ranking highest. Highest priority in this sense means most relevant for augmenting/updating a dataset, with EML being the most relevant because it is the most informative type. false false type
/dataset/metadata/{ID} GET Metadata Description Get a metadata description by its identifier {ID} false false
/dataset/metadata/{ID}/document GET Metadata Document Gets the actual metadata description's document by its identifier {ID} false false
/dataset/metadata/{ID} DELETE Deletes a metadata description entry and its document by its identifier {ID} true false
/dataset/deleted GET Lists all datasets that are marked as deleted false true
/dataset/duplicate GET Lists all datasets that are marked as a duplicate of another false true
/dataset/withNoEndpoint GET Lists all datasets (are not sub datasets) having no endpoint false true

Dataset Search

The dataset search API provides search services for datasets.

Resource URL Method Response Description Paging Parameters
/dataset/search GET DatasetSearchResult Full text search across all datasets. Results are ordered by relevance. true q, country, type, subtype, keyword, publishingOrg, hostingOrg, decade, publishingCountry, continent, hl, facet, facetMincount, facetMultiselect
/dataset/suggest GET DatasetSearchResult Search that returns up to 20 matching datasets. Results are ordered by relevance. false q, country, type, subtype, keyword, publishingOrg, hostingOrg, decade, publishingCountry, continent

Dataset Metrics

The dataset metrics API provides metrics for datasets of type CHECKLIST only.

Resource URL Method Response Description Paging Parameters
/dataset/{UUID}/metrics GET DatasetMetrics Get various metrics for a checklist. Metrics include the number of species, the number of synonyms, counts by rank, counts by vernacular name language, etc. false

Installations

The installation API provides CRUD and discovery services for installations.

Please note deletion of installations is logical, meaning installation entries remain registered forever and only get a deleted timestamp. On the other hand, deletion of an installation's contacts, endpoints, identifiers, tags, machine tags, and comments is physical, meaning the entries are permanently removed.

Resource URL Method Response Description Auth Paging Parameters
/installation GET Installation List Lists all installations false true q, identifier, identifierType
/installation POST UUID Creates a new installation true false
/installation/{UUID} GET Installation Gets details for the single installation false false
/installation/{UUID} PUT Updates the installation true false
/installation/{UUID} DELETE Deletes the installation. The installation entry gets a deleted timestamp but remains registered. true false
/installation/{UUID}/contact GET Contact List Lists all contacts for the installation false false
/installation/{UUID}/contact POST ID Creates and adds an installation contact true false
/installation/{UUID}/contact/{ID} DELETE Deletes an installation contact with contact identifier {ID} true false
/installation/{UUID}/contact/{ID} PUT Updates an installation contact with contact identifier {ID} true false
/installation/{UUID}/endpoint GET Endpoint List Lists the installation endpoints false false
/installation/{UUID}/endpoint POST ID Creates an installation endpoint true false
/installation/{UUID}/endpoint/{ID} DELETE Deletes an installation endpoint with identifier {ID} true false
/installation/{UUID}/identifier GET Identifier List Lists the installation's identifiers false false
/installation/{UUID}/identifier POST ID Creates a new installation identifier true false
/installation/{UUID}/identifier/{ID} DELETE Deletes an installation's identifier with identifier {ID}> true false
/installation/{UUID}/tag GET Tag List Lists all tags for an installation false false
/installation/{UUID}/tag POST ID Creates and adds an installation tag true false
/installation/{UUID}/tag/{ID} DELETE Deletes the installation tag with tag identifier {ID} true false
/installation/{UUID}/machineTag GET Machine Tag List Lists all machine tags for an installation false false
/installation/{UUID}/machineTag POST ID Creates and adds an installation machine tag true false
/installation/{UUID}/machineTag/{ID} DELETE Deletes the installation machine tag with machine tag identifier {ID} false false
/installation/{UUID}/comment GET Comment List Lists all comments for an installation false false
/installation/{UUID}/comment POST ID Creates and adds an installation comment true false
/installation/{UUID}/comment DELETE Deletes the installation comment with comment identifier {ID} true false
/installation/{UUID}/dataset GET Dataset List Lists datasets served by the installation false true
/installation/deleted GET Lists the deleted installations false true
/installation/nonPublishing GET Lists the installations serving 0 datasets false true

Organizations

The organization API provides CRUD and discovery services for organizations. Its most prominent use on the GBIF portal is to drive the data publisher search.

Please note deletion of organizations is logical, meaning organization entries remain registered forever and only get a deleted timestamp. On the other hand, deletion of an organization's contacts, endpoints, identifiers, tags, machine tags, and comments is physical, meaning the entries are permanently removed.

Resource URL Method Response Description Auth Paging Parameters
/organization GET Organization List Lists all organizations false true q, country, identifier, identifierType
/organization POST UUID Creates a new organization true false
/organization/{UUID} GET Organization Gets details for the single organization false false
/organization/{UUID} PUT Updates the organization true false
/organization/{UUID} DELETE Deletes the organization. The organization entry gets a deleted timestamp but remains registered. true false
/organization/{UUID}/contact GET Contact List Lists all contacts for the organization false false
/organization/{UUID}/contact POST ID Creates and adds an organization contact true false
/organization/{UUID}/contact/{ID} DELETE Deletes an organization contact with contact identifier {ID} true false
/organization/{UUID}/contact/{ID} PUT Updates an organization contact with contact identifier {ID} true false
/organization/{UUID}/endpoint GET Endpoint List Lists the organization endpoints false false
/organization/{UUID}/endpoint POST ID Creates an organization endpoint true false
/organization/{UUID}/endpoint/{ID} DELETE Deletes an organization endpoint with identifier {ID} true false
/organization/{UUID}/identifier GET Identifier List Lists the organization's identifiers false false
/organization/{UUID}/identifier POST ID Creates a new organization identifier true false
/organization/{UUID}/identifier/{ID} DELETE Deletes an organization's identifier with identifier {ID}> true false
/organization/{UUID}/tag GET Tag List Lists all tags for an organization false false
/organization/{UUID}/tag POST ID Creates and adds an organization tag true false
/organization/{UUID}/tag/{ID} DELETE Deletes the organization tag with tag identifier {ID} true false
/organization/{UUID}/machineTag GET Machine Tag List Lists all machine tags for an organization false false
/organization/{UUID}/machineTag POST ID Creates and adds an organization machine tag true false
/organization/{UUID}/machineTag/{ID} DELETE Deletes the organization machine tag with machine tag identifier {ID} false false
/organization/{UUID}/comment GET Comment List Lists all comments for an organization false false
/organization/{UUID}/comment POST ID Creates and adds an organization comment true false
/organization/{UUID}/comment DELETE Deletes the organization comment with comment identifier {ID} true false
/organization/{UUID}/hostedDataset GET Dataset Lists the hosted datasets (datasets hosted by installations hosted by the organization) false true
/organization/{UUID}/publishedDataset GET Dataset Lists the published datasets (datasets published by the organization) false true
/organization/{UUID}/installation GET Installation Lists the technical installations hosted by this organization false true
/organization/deleted GET Organization List Lists the deleted organizations false true
/organization/pending GET Organization List Lists the organizations whose endorsement is pending false true
/organization/nonPublishing GET Organization List Lists the organizations publishing 0 datasets false true

Nodes

The node API provides CRUD and discovery services for nodes. Its most prominent use on the GBIF portal is to drive the country pages.

Please note deletion of nodes is logical, meaning node entries remain registered forever and only get a deleted timestamp. On the other hand, deletion of an node's contacts, endpoints, identifiers, tags, machine tags, and comments is physical, meaning the entries are permanently removed.

Resource URL Method Response Description Auth Paging Parameters
/node GET Node List Lists all nodes false true q, identifier, identifierType
/node POST UUID Creates a new node true false
/node/{UUID} GET Node Gets details for the single node false false
/node/{UUID} PUT Updates the node true false
/node/{UUID} DELETE Deletes the node. The node entry gets a deleted timestamp but remains registered. true false
/node/{UUID}/organization GET Organization Lists organizations endorsed by the node false true
/node/{UUID}/endpoint GET Endpoint List Lists the node endpoints false false
/node/{UUID}/endpoint POST ID Creates a node endpoint true false
/node/{UUID}/endpoint/{ID} DELETE Deletes a node endpoint with identifier {ID} true false
/node/{UUID}/identifier GET Identifier List Lists the node's identifiers false false
/node/{UUID}/identifier POST ID Creates a new node identifier true false
/node/{UUID}/identifier/{ID} DELETE Deletes a node's identifier with identifier {ID}> true false
/node/{UUID}/tag GET Tag List Lists all tags for a node false false
/node/{UUID}/tag POST ID Creates and adds a node tag true false
/node/{UUID}/tag/{ID} DELETE Deletes the node tag with tag identifier {ID} true false
/node/{UUID}/machineTag GET Machine Tag List Lists all machine tags for a node false false
/node/{UUID}/machineTag POST ID Creates and adds a node machine tag true false
/node/{UUID}/machineTag/{ID} DELETE Deletes the node machine tag with machine tag identifier {ID} false false
/node/{UUID}/comment GET Comment List Lists all comments for a node false false
/node/{UUID}/comment POST ID Creates and adds a node comment true false
/node/{UUID}/comment DELETE Deletes the node comment with comment identifier {ID} true false
/node/pendingEndorsement GET Organization List Lists all organizations whose endorsement is pending false true
/node/{UUID}/pendingEndorsement GET Organization List Lists all organizations whose endorsement by the node is pending false true
/node/country GET ISO-CODE List Lists names of all GBIF member countries false false
/node/activeCountries GET ISO-CODE List Lists of all GBIF member countries that are either voting or associate participants false false
/node/country/{ISO-CODE} GET Node Gets the country node by ISO 639-1 (2 letter) or ISO 639-2 (3 letter) country code false false
/node/{UUID}/dataset GET Dataset List Lists datasets published by organizations endorsed by the node false true
/node/{UUID}/installation GET Installation List Lists installations hosted by organizations endorsed by the node false true

Networks

The network API provides CRUD and discovery services for networks.

Please note deletion of networks is logical, meaning network entries remain registered forever and only get a deleted timestamp. On the other hand, deletion of an network's contacts, endpoints, identifiers, tags, machine tags, and comments is physical, meaning the entries are permanently removed.

Resource URL Method Response Description Auth Paging Parameters
/network GET Network List Lists all networks false true q, identifier, identifierType
/network POST UUID Creates a new network true false
/network/{UUID} GET Network Gets details for the single network false false
/network/{UUID} PUT Updates the network true false
/network/{UUID} DELETE Deletes the network. The network entry gets a deleted timestamp but remains registered. true false
/network/{UUID}/contact GET Contact List Lists all contacts for the network false false
/network/{UUID}/contact POST ID Creates and adds a network contact true false
/network/{UUID}/contact/{ID} DELETE Deletes a network contact with contact identifier {ID} true false
/network/{UUID}/contact/{ID} PUT Updates a network contact with contact identifier {ID} true false
/network/{UUID}/endpoint GET Endpoint List Lists the network endpoints false false
/network/{UUID}/endpoint POST ID Creates a network endpoint true false
/network/{UUID}/endpoint/{ID} DELETE Deletes a network endpoint with identifier {ID} true false
/network/{UUID}/identifier GET Identifier List Lists the network's identifiers false false
/network/{UUID}/identifier POST ID Creates a new network identifier true false
/network/{UUID}/identifier/{ID} DELETE Deletes a network's identifier with identifier {ID}> true false
/network/{UUID}/tag GET Tag List Lists all tags for a network false false
/network/{UUID}/tag POST ID Creates and adds a network tag true false
/network/{UUID}/tag/{ID} DELETE Deletes the network tag with tag identifier {ID} true false
/network/{UUID}/machineTag GET Machine Tag List Lists all machine tags for the network false false
/network/{UUID}/machineTag POST ID Creates and adds a network machine tag true false
/network/{UUID}/machineTag/{ID} DELETE Deletes the network machine tag with machine tag identifier {ID} false false
/network/{UUID}/comment GET Comment List Lists all comments for the network false false
/network/{UUID}/comment POST ID Creates and adds a network comment true false
/network/{UUID}/comment DELETE Deletes the network comment with comment identifier {ID} true false
/network/{UUID}/constituents GET Dataset List Lists dataset constituents of the network false true
/network/{UUID}/constituents POST Adds an existing dataset to the list of constituents of a network true false
/network/{UUID}/constituents DELETE ID Deletes an existing constituent dataset from a network true false

Query parameters explained

The following parameters are for use exclusively with the Registry API described above.

Parameter Description
continent Not yet implemented, but will eventually allow filtering datasets by their continent(s) as given in our Continent enum.
country Filters by country given as a ISO 639-1 (2 letter) country code. Not yet implemented for use with dataset search, but will eventually search on the countries within the geospatial coverage of the dataset.
decade Filters datasets by their temporal coverage broken down to decades. Decades are given as a full year, e.g. 1880, 1960, 2000, etc, and will return datasets wholly contained in the decade as well as those that cover the entire decade or more. Facet by decade to get the break down, e.g. /search?facet=DECADE&limit=0
facet A list of facet names used to retrieve the 100 most frequent values for a field. Allowed facets are: type, keyword, publishingOrg, hostingOrg, decade, and publishingCountry. Additionally subtype and country are legal values but not yet implemented, so data will not yet be returned for them.
facetMincount Used in combination with the facet parameter. Set facetMincount={#} to exclude facets with a count less than {#}, e.g. /search?facet=type&limit=0&facetMincount=10000 only shows the type value 'OCCURRENCE' because 'CHECKLIST' and 'METADATA' have counts less than 10000.
facetMultiselect Used in combination with the facet parameter. Set facetMultiselect=true to still return counts for values that are not currently filtered, e.g. /search?facet=type&limit=0&type=CHECKLIST&facetMultiselect=true still shows type values 'OCCURRENCE' and 'METADATA' even though type is being filtered by type=CHECKLIST
hl Set hl=true to highlight terms matching the query when in fulltext search fields. The highlight will be an emphasis tag of class 'gbifH1' e.g. /search?q=plant&hl=true. Fulltext search fields include: title, keyword, country, publishing country, publishing organization title, hosting organization title, and description. One additional full text field is searched which includes information from metadata documents, but the text of this field is not returned in the response.
hostingOrg Filters datasets by their hosting organization UUID key
identifier The value for this parameter can be a simple string or integer, e.g. identifier=120
identifierType Used in combination with the identifier parameter to filter identifiers by identifier type as given in our IdentifierType enum
keyword Filters datasets by a case insensitive plain text keyword. The search is done on the merged collection of tags, the dataset keywordCollections and temporalCoverages.
publishingCountry Filters datasets by their owining organization's country given as a ISO 639-1 (2 letter) country code
publishingOrg Filters datasets by their publishing organization UUID key
q Simple search parameter. The value for this parameter can be a simple word or a phrase. Wildcards can be added to the simple word parameters only, e.g. q=*puma*
subtype Not yet implemented, but will eventually allow filtering of datasets by their dataset subtype as given in our DatasetSubtype enum.
type For datasets, filters by dataset type as given in our DatasetType enum. For metadata documents, filters by the metadata type as given in our MetadataType enum