Registry API

https://api.gbif.org/v1/

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, machineTagNamespace, machineTagName, machineTagValue
/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}/crawl	POST		Schedules a new ingestion of the dataset	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}/networks	GET		Lists the networks the dataset belongs to	false	false
/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/doi/{DOI}	GET		Lists datasets with the given DOI.	false	true
/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, license, keyword, publishingOrg, hostingOrg, endorsingNodeKey, decade, publishingCountry, projectId, hostingCountry, continent, networkKey, hl, facet, facetMincount, facetMultiselect
/dataset/search/export	GET	DatasetSearchResult	Export the entire search results to TSV or CSV file	false	q, country, type, subtype, license, keyword, publishingOrg, hostingOrg, endorsingNodeKey, decade, publishingCountry, hostingCountry, continent, networkKey, format
/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, projectId

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 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, type, machineTagNamespace, machineTagName, machineTagValue
/installation	POST	UUID	Creates a new installation	true	false
/installation/{UUID}	GET	Installation	Gets details for a 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, isEndorsed, machineTagNamespace, machineTagName, machineTagValue
/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, machineTagNamespace, machineTagName, machineTagValue
/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, machineTagNamespace, machineTagName, machineTagValue
/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

}

Collections

The collections API provides CRUD services for collections and institutions entities. The data was originally migrated from GrSciColl and adapted to follow the same conventions as other registry services. Therefore, the deletion of collections and institutions is logical, meaning these entries remain registered forever and only get a deleted timestamp. On the other hand, the deletion of tags and identifiers is physical, meaning the entries are permanently removed.

Please note that this part of the API is still under development, and may change in the future.

Collection

This API provides CRUD services for the collection entity. A collection can be associated with an institution and can have a list of contacts, machine tags, tags, comments and identifiers.

Resource URL	Method	Response	Description	Auth	Paging	Parameters
/grscicoll/collection	GET	Collection List	Lists all collections	false	true	q, institution, contact, code, name, alternativeCode, identifier, identifierType, machineTagNamespace, machineTagName, machineTagValue, country, active, contentType, preservationType, accessionStatus, personalCollection, masterSourceType, displayOnNHCPortal, numberSpecimens
/grscicoll/collection	POST	UUID	Creates a new collection	true	false
/grscicoll/collection/{UUID}	GET	Collection	Gets details for the collection	false	false
/grscicoll/collection/{UUID}	PUT		Updates the collection	true	false
/grscicoll/collection/{UUID}	DELETE		Deletes the collection. The collection entry gets a deleted timestamp but remains registered.	true	false
/grscicoll/collection/{UUID}/contactPerson	GET	Contact List	Lists all contacts for the collection	false	false
/grscicoll/collection/{UUID}/contactPerson	POST		Adds a contact to the collection. The contact must be passed in the body.	true	false
/grscicoll/collection/{UUID}/contactPerson/{ID}	PUT		Updates the contact with key {ID} of the collection. The updated contact must be passed in the body.	true	false
/grscicoll/collection/{UUID}/contactPerson/{ID}	DELETE		Deletes the contact with key {ID} from the collection	true	false
/grscicoll/collection/{UUID}/identifier	GET	Identifier List	Lists the identifiers of the collection	false	false
/grscicoll/collection/{UUID}/identifier	POST	ID	Creates a new collection identifier	true	false
/grscicoll/collection/{UUID}/identifier/{ID}	DELETE		Deletes the identifier with ID {ID} from the collection	true	false
/grscicoll/collection/{UUID}/tag	GET	Tag List	Lists all tags for a collection	false	false
/grscicoll/collection/{UUID}/tag	POST	ID	Creates and adds a tag to the collection	true	false
/grscicoll/collection/{UUID}/tag/{ID}	DELETE		Deletes the tag with ID {ID} from the collection	true	false
/grscicoll/collection/{UUID}/machineTag	GET	Machine Tag List	Lists all machine tags for a collection	false	false
/grscicoll/collection/{UUID}/machineTag	POST	ID	Create and add a collection machine tag	true	false
/grscicoll/collection/{UUID}/machineTag/{ID}	DELETE		Deletes the collection machine tag with machine tag identifier {ID}	false	false
/grscicoll/collection/deleted	GET	Deleted Collections List	Lists the deleted collections	false	true	replacedBy
/grscicoll/collection/suggest	GET	Suggested Search Result	Search that returns up to 20 matching collections. Results are ordered by relevance	false	false
/grscicoll/collection/{UUID}/comment	GET	Comment List	Lists all comments for a collection	false	false
/grscicoll/collection/{UUID}/comment	POST	ID	Create and add a collection comment	true	false
/grscicoll/collection/{UUID}/comment/{ID}	DELETE		Deletes the collection comment with comment identifier {ID}	true	false
/grscicoll/collection/{UUID}/occurrenceMapping	GET	Occurrence Mapping List	Lists all occurrence mappings for a collection	false	false
/grscicoll/collection/{UUID}/occurrenceMapping	POST	ID	Create and add an occurrence mapping	true	false
/grscicoll/collection/{UUID}/occurrenceMapping/{ID}	DELETE		Deletes the collection occurrence mapping with identifier {ID}	true	false
/grscicoll/collection/possibleDuplicates	GET	Collections Possible Duplicates List	Lists possible duplicates	false	false	sameName, sameFuzzyName, sameCode, sameCountry, sameCity, sameInstitution, inCountries, notInCountries, excludeKeys, inInstitutions, notInInstitutions
/grscicoll/collection/{UUID}/merge	POST		Merges a collection with another collection	true	false
/grscicoll/collection/changeSuggestion	GET	Change Suggestions List	Lists all change suggestions for collections	false	true	status, type, proposerEmail, entityKey
/grscicoll/collection/changeSuggestion	POST		Creates a collection change suggestion. The possible types are CREATE, UPDATE, DELETE and MERGE.	false	false
/grscicoll/collection/changeSuggestion/{ID}	GET	Change Suggestion	Gets details of a collection change suggestion	false	false
/grscicoll/collection/changeSuggestion/{ID}	PUT		Updates a collection change suggestion	true	false
/grscicoll/collection/changeSuggestion/{ID}/apply	PUT		Applies a collection change suggestion	true	false
/grscicoll/collection/changeSuggestion/{ID}/discard	PUT		Discards a collection change suggestion	true	false
/grscicoll/collection/export	GET	Export in CSV or TSV format	Collections export	false	false	format, q, institution, contact, code, name, alternativeCode, identifier, identifierType, machineTagNamespace, machineTagName, machineTagValue, country, active, contentType, preservationType, accessionStatus, personalCollection, masterSourceType, displayOnNHCPortal, numberSpecimens
/grscicoll/collection/import	POST	UUID	Imports a collection from a dataset. The body must contain the datasetKey and the collectionCode.	true	false
/grscicoll/collection/{UUID}/masterSourceMetadata	GET	Master source metadata of the entity	Returns the master source of the entity	false	false
/grscicoll/collection/{UUID}/masterSourceMetadata	POST		Adds a master source metadata to the collection. The metadata must be passed in the body.	true	false
/grscicoll/collection/{UUID}/masterSourceMetadata	DELETE		Deletes the master source metadata from the collection	true	false

Institution

This API provides CRUD services for the institution entity. An institution can have a list of contacts, machine tags, comments, tags and identifiers.

Resource URL	Method	Response	Description	Auth	Paging	Parameters
/grscicoll/institution	GET	Institution List	Lists all institutions	false	true	q, contact, code, name, alternativeCode, identifier, identifierType, machineTagNamespace, machineTagName, machineTagValue, country, active, type, institutionalGovernance, discipline, masterSourceType, displayOnNHCPortal, numberSpecimens
/grscicoll/institution	POST	UUID	Creates a new institution	true	false
/grscicoll/institution/{UUID}	GET	Institution	Gets details for the institution	false	false
/grscicoll/institution/{UUID}	PUT		Updates the institution	true	false
/grscicoll/institution/{UUID}	DELETE		Deletes the institution. The institution entry gets a deleted timestamp but remains registered.	true	false
/grscicoll/institution/{UUID}/contactPerson	GET	Contact List	Lists all contacts for the institution	false	false
/grscicoll/institution/{UUID}/contactPerson	POST		Adds a contact to the institution. The contact must be passed in the body.	true	false
/grscicoll/institution/{UUID}/contactPerson/{ID}	PUT		Updates the contact with key {ID} of the institution. The updated contact must be passed in the body.	true	false
/grscicoll/institution/{UUID}/contactPerson/{ID}	DELETE		Deletes the contact with key {ID} from the institution	true	false
/grscicoll/institution/{UUID}/identifier	GET	Identifier List	Lists the identifiers of the institution	false	false
/grscicoll/institution/{UUID}/identifier	POST	ID	Creates a new institution identifier	true	false
/grscicoll/institution/{UUID}/identifier/{ID}	DELETE		Deletes the identifier with ID {ID} from the institution	true	false
/grscicoll/institution/{UUID}/tag	GET	Tag List	Lists all tags for a institution	false	false
/grscicoll/institution/{UUID}/tag	POST	ID	Creates and adds a tag to the institution	true	false
/grscicoll/institution/{UUID}/tag/{ID}	DELETE		Deletes the tag with ID {ID} from the institution	true	false
/grscicoll/institution/{UUID}/machineTag	GET	Machine Tag List	Lists all machine tags for a institution	false	false
/grscicoll/institution/{UUID}/machineTag	POST	ID	Create and add a institution machine tag	true	false
/grscicoll/institution/{UUID}/machineTag/{ID}	DELETE		Deletes the institution machine tag with machine tag identifier {ID}	false	false
/grscicoll/institution/deleted	GET	Deleted Institutions List	Lists the deleted institutions	false	true	replacedBy
/grscicoll/institution/suggest	GET	Suggested Search Result	Search that returns up to 20 matching institutions. Results are ordered by relevance	false	false
/grscicoll/institution/{UUID}/comment	GET	Comment List	Lists all comments for an institution	false	false
/grscicoll/institution/{UUID}/comment	POST	ID	Create and add an institution comment	true	false
/grscicoll/institution/{UUID}/comment/{ID}	DELETE		Deletes the institution comment with comment identifier {ID}	true	false
/grscicoll/institution/{UUID}/occurrenceMapping	GET	Occurrence Mapping List	Lists all occurrence mappings for an institution	false	false
/grscicoll/institution/{UUID}/occurrenceMapping	POST	ID	Create and add an institution occurrence mapping	true	false
/grscicoll/institution/{UUID}/occurrenceMapping/{ID}	DELETE		Deletes the institution occurrence mapping with identifier {ID}	true	false
/grscicoll/institution/possibleDuplicates	GET	Institutions Possible Duplicates List	Lists possible duplicates	false	false	sameName, sameFuzzyName, sameCode, sameCountry, sameCity, inCountries, notInCountries, excludeKeys
/grscicoll/institution/{UUID}/merge	POST		Merges an institution with another institution	true	false
/grscicoll/institution/{UUID}/convertToCollection	POST		Converts an institution into a collection	true	false
/grscicoll/institution/changeSuggestion	GET	Change Suggestions List	Lists all change suggestions for institutions	false	true	status, type, proposerEmail, entityKey
/grscicoll/institution/changeSuggestion	POST		Creates an institution change suggestion. The possible types are CREATE, UPDATE, DELETE, MERGE and CONVERSION_TO_COLLECTION.	false	false
/grscicoll/institution/changeSuggestion/{ID}	GET	Change Suggestion	Gets details of an institution change suggestion	false	false
/grscicoll/institution/changeSuggestion/{ID}	PUT		Updates an institution change suggestion	true	false
/grscicoll/institution/changeSuggestion/{ID}/apply	PUT		Applies an institution change suggestion	true	false
/grscicoll/institution/changeSuggestion/{ID}/discard	PUT		Discards an institution change suggestion	true	false
/grscicoll/institution/export	GET	Export in CSV or TSV format	Institutions export	false	false	format, q, code, name, alternativeCode, identifier, identifierType, machineTagNamespace, machineTagName, machineTagValue, country, active, type, institutionalGovernance, discipline, masterSourceType, displayOnNHCPortal, numberSpecimens
/grscicoll/institution/import	POST	UUID	Imports an institution from an organization. The body must contain the organizationKey and the institutionCode.	true	false
/grscicoll/institution/{UUID}/masterSourceMetadata	GET	Master source metadata of the entity	Returns the master source of the entity	false	false
/grscicoll/institution/{UUID}/masterSourceMetadata	POST		Adds a master source metadata to the institution. The metadata must be passed in the body.	true	false
/grscicoll/institution/{UUID}/masterSourceMetadata	DELETE		Deletes the master source metadata from the institution	true	false

Lookup

This API provides a service to lookup institutions and collections. It can be used to lookup for institutions, collections or both at the same time. Besides the matches, the response also provides information to help understand how the match was done.

Resource URL	Method	Response	Description	Auth	Paging	Parameters
/grscicoll/lookup	GET	Matches found	Lists all the matches found	false	false	institutionCode, ownerInstitutionCode, institutionId, collectionCode, collectionId, datasetKey, country, verbose

Explanation of the lookup parameters:

Parameter	Description
institutionCode	The code of an institution
ownerInstitutionCode	The code of the owner institution. This parameter is only used to detect the cases when the instution and the owner institution are different. If that happens, the match is not considered accepted
institutionId	The identifier of an institution
collectionCode	The code of a collection
collectionId	The identifier of a collection
datasetKey	Institutions and collections can be linked manually to datasets by using occurrence mappings. If the dataset key parameter is set it will be used to try to match an occurrence mapping that contains that dataset. This manual mapping only happens if no exact matches were found
country	ISO 639-1 (2 letter) country code. This parameter is only used as a discriminator when more than 1 candidate is found
verbose	Boolean parameter(true or false). If set to true, it returns the accepted matches and other alternatives that were also found. Otherwise, it only returns the accepted ones

Explanation of the match status in the response:

Status	Description
ACCEPTED	The match is considered accepted because both the code and the identifier matched and only 1 candidate was found
AMBIGUOUS	Multiple candidates were found with the same level of confidence and it can't be determined which one should be accepted
AMBIGUOUS_EXPLICIT_MAPPINGS	Multiple candidates were found in the occurrence mappings with the same level of confidence and it can't be determined which one should be accepted
AMBIGUOUS_OWNER	At least 1 possible institution match was found but none of them match with the owner institution specified
AMBIGUOUS_INSTITUTION_MISMATCH	At least 1 possible collection match was found but none of them belong to the institution matched
DOUBTFUL	A match was found but it was matched fuzzily. To know more about why this has happened see the "reasons" returned in the response. A common case is when the name is used instead of the code or the identifier

Search

This API provides a service to search institutions and collections. It searches in both institutions and collections and it highlights the matching fields (optional).

Resource URL	Method	Response	Description	Auth	Paging	Parameters
/grscicoll/search	GET	Results found	Searches for institutions and collections	false	false	q, hl, entityType, displayOnNHCPortal, country

Audit Log

This services provides an audit log that tracks all the changes made to GRSciColl entities. Its usage is reserved for admins.

Resource URL	Method	Response	Description	Auth	Paging	Parameters
/grscicoll/auditLog	GET	Results found	Lists the GRSciColl Audit Log	true	true	traceId, collectionEntityType, subEntityType, operation, collectionEntityKey, createdBy, dateFrom, dateTo

Query parameters explained

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

Parameter	Description
accessionStatus	Accesion status of a GrSciColl collection
active	Active status of a GrSciColl institution or collection
alternativeCode	Alternative code of a GrSciColl institution or collection
code	Code of a GrSciColl institution or collection
collectionEntityKey	Key of the institution or collection being modified
collectionEntityType	Entity type used in the GRSciColl audit log: INSTITUTION, COLLECTION)
contentType	Content type of a GrSciColl collection. Accepts multiple values, e.g.: contentType=PALEONTOLOGICAL_OTHER&contentType=EARTH_PLANETARY_MINERALS
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. Country codes are listed in our Country enum.
createdBy	User who did the change in a GRSciColl audit log
dateFrom	Filters GRSciColl audit logs after a specific date (format yyyy-MM-dd)
dateTo	Filters GRSciColl audit logs until a specific date (format yyyy-MM-dd)
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
discipline	Discipline of a GrSciColl institution. Accepts multiple values, e.g.: discipline=ARCHAEOLOGY_PREHISTORIC&discipline=ARCHAEOLOGY_HISTORIC
displayOnNHCPortal	Flag that indicates if a collection or institution should be displayed in the Natural History Collections portal
endorsingNodeKey	Node key that endorsed this dataset's publisher
entityKey	The key of the entity of a change suggestion in GRSciColl
entityType	GRSciColl entity type: COLLECTION or INSTITUTION. If not specified both types are returned
excludeKeys	Discards entities with any of the keys specified. For multiple values separate them by commas(excludeKeys=7e730f02-2129-45b0-a76e-7e5ff43fda3f,0403ac88-682b-44d8-91bb-6d76f155e519) or send it multiple times(excludeKeys=7e730f02-2129-45b0-a76e-7e5ff43fda3f&excludeKeys=0403ac88-682b-44d8-91bb-6d76f155e519)
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
format	Format of an export: TSV(default) or CSV
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.
hostingCountry	Filters datasets by their hosting organization's country given as a ISO 639-1 (2 letter) country code
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
inCountries	Filters duplicates to return only the ones that contain one of the countries specified. For multiple values separate them by commas(inCountries=FI,DE) or send it multiple times(inCountries=FI&inCountries=DE)
inInstitutions	Filters duplicates to return only the ones that belong to any of the institutions specified. For multiple values separate them by commas(inInstitutions=7e730f02-2129-45b0-a76e-7e5ff43fda3f,0403ac88-682b-44d8-91bb-6d76f155e519) or send it multiple times(inInstitutions=7e730f02-2129-45b0-a76e-7e5ff43fda3f&inInstitutions=0403ac88-682b-44d8-91bb-6d76f155e519)
installationType	Filters installations by their type. The possible types is defined in our InstallationType enum
institution	Filters collections by the institution key specified
institutionalGovernance	Instutional governance of a GrSciColl institution
isEndorsed	Filters organizations by whether they are endorsed or not
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.
license	The type of license applied to the dataset.
machineTagName	Filters for entities with a machine tag with the specified name (use in combination with the machineTagNamespace parameter).
machineTagNamespace	Filters for entities with a machine tag in the specified namespace
machineTagValue	Filters for entities with a machine tag with the specified value (use in combination with the machineTagNamespace and machineTagName parameters).
masterSourceType	The master source type of a GRSciColl institution or collection(GRSCICOLL, GBIF_REGISTRY, IH)
name	Name of a GrSciColl institution or collection
networkKey	Network associated to a dataset
notInCountries	Discards duplicates from any of the countries specified. For multiple values separate them by commas(notInCountries=FI,DE) or send it multiple times(notInCountries=FI&notInCountries=DE)
notInInstitutions	Filters duplicates to return only the ones that don't belong to any of the institutions specified. For multiple values separate them by commas(notInInstitutions=7e730f02-2129-45b0-a76e-7e5ff43fda3f,0403ac88-682b-44d8-91bb-6d76f155e519) or send it multiple times(notInInstitutions=7e730f02-2129-45b0-a76e-7e5ff43fda3f&notInInstitutions=0403ac88-682b-44d8-91bb-6d76f155e519)
numberSpecimens	Number of specimens of a collection or institution. It supports both exact values and ranges. The range supports the wildcard , e.g.: ,100
operation	Operation of a GRSciColl audit log: CREATE, UPDATE, DELETE, LINK, UNLINK, REPLACE, CONVERSION_TO_COLLECTION, APPLY_SUGGESTION, DISCARD_SUGGESTION
personalCollection	Flag for personal GRSciColl collections
preservationType	Preservation type of a GrSciColl collection. Accepts multiple values, e.g.: preservationType=SAMPLE_CRYOPRESERVED&preservationType=SAMPLE_FLUID_PRESERVED
projectId	Filter or facet based on the project ID of a given dataset. A dataset can have a project id if it is the result of a project. multiple datasets can have the same project id.
proposerEmail	The email of the person who suggested a change in GRSciColl
publishingCountry	Filters datasets by their owning 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
replacedBy	UUID of the replacement of a GRSciColl institution or collection
sameCity	Looks for collections/institutions with the same city if true or with different city if false. Ignored if not sent.
sameCode	Looks for collections/institutions with the same code if true or with different code if false. Ignored if not sent.
sameCountry	Looks for collections/institutions with the same country if true or with different country if false. Ignored if not sent.
sameFuzzyName	Looks for collections/institutions with the same fuzzy name if true or with different fuzzy name if false. Ignored if not sent.
sameInstitution	Looks for collections with the same institution if true or with different institution if false. Ignored if not sent.
sameName	Looks for collections/institutions with the same name if true or with different name if false. Ignored if not sent.
status	Status of a change suggestion: PENDING, APPLIED, DISCARDED)
subEntityType	Subentity type used in the GRSciColl audit log: Identifier, MachineTag, Comment, Tag, OccurrenceMapping, Contact, ChangeSuggestionDto
subtype	Not yet implemented, but will eventually allow filtering of datasets by their dataset subtype as given in our DatasetSubtype enum.
traceId	Trace ID of a GRSciColl audit log
type	Type of a GrSciColl institution

OAI-PMH

In addition to the RESTful JSON API, Datasets are exposed using OAI-PMH. Two metadata formats can be retrieved: Ecological Metadata Language (EML) and OAI Dublin Core. Datasets are grouped into sets according to type, country and installation.

The endpoint is at https://api.gbif.org/v1/oai-pmh/registry

Example queries:

Retrieve information about the OAI-PMH service: Identify.
Retrieve a list of available sets (dataset types, countries and serving installations): ListSets.

Sets have names like dataset_type:CHECKLIST and country:NL.
Retrieve the identifiers for all datasets from a particular installation: ListIdentifiers.

According to the OAI-PMH protocol, metadataPrefix must be set to either oai_dc or eml, even though both formats are supported for all datasets.
Retrieve the metadata for all datasets served by installations in a country: ListRecords.

Country codes are based on the ISO 3166-1 standard.
Some queries will return more than one page of results. In this case, the XML will end with a resumption token element, for example: <resumptionToken cursor="1">MToxMDB8Mjpjb3VudHJ5Ok5MfDM6fDQ6fDU6b2FpX2Rj</resumptionToken> The second page of results can be retrieved like this: Resume.

Full details of the protocol can be found in the The Open Archives Initiative Protocol for Metadata Harvesting, in particular the section on Protocol Requests and, Responses.