Getting Started with APIs¶
If you are a researcher or curator who wants to automate parts of your workflow, this section should help you get started. The Introduction section lists resources for other groups who may be interested in Dataverse Software APIs such as developers of integrations and support teams.
Rather than using a production Dataverse installation, API users are welcome to use http://demo.dataverse.org for testing. You can email email@example.com if you have any trouble with this server.
Many Dataverse Software APIs require an API token.
Once you have identified a server to test with, create an account, click on your name, and get your API token. For more details, see the API Tokens and Authentication section.
The examples in this guide use curl for the following reasons:
curl commands are succinct.
curl commands can be copied and pasted into a terminal.
This guide is programming language agnostic. It doesn’t prefer any particular programming language.
You’ll find curl examples that look like this:
export SERVER_URL=https://demo.dataverse.org export QUERY=data curl $SERVER_URL/api/search?q=$QUERY
What’s going on above is the declaration of “environment variables” that are substituted into a curl command. You should run the “export” commands but change the value for the server URL or the query (or whatever options the command supports). Then you should be able to copy and paste the curl command and it should “just work”, substituting the variables like this:
If you ever want to check an environment variable, you can “echo” it like this:
A quick example search for the word “data” is https://demo.dataverse.org/api/search?q=data
See the Search API section for details.
It’s also possible to find recently published datasets via OAI-PMH.
The Data Access API section explains how to download files.
To download all the files in a dataset, see Downloading All Files in a Dataset.
In order to download individual files, you must know their database IDs which you can get from the
dataverse_json metadata at the dataset level. See Export Metadata of a Dataset in Various Formats.
Dataset metadata is available in a variety of formats listed at Supported Metadata Export Formats.
In addition to the tasks listed above, your Dataverse installation supports many other operations via API.
If you’re looking for some inspiration for how you can use the Dataverse Software APIs, there are open source projects that integrate with the Dataverse Software listed in the Apps section.