This guide is written for those who may be relatively new to APIs and even new to programming. Rather than a comprehensive guide to using the Figshare API, we hope this gives you a feel for how it works and what it is capable of. This is a first step in going beyond the already powerful repository management and reporting tools available in the Figshare user interface.
Institutions may be interested in how the API can be used to customize the user interface or perform migrations. We’ve provided examples of these at the bottom of this page.
There are many more resources on a GitHub website that was created for a workshop on the API.
Figshare strives to be adaptable to your use case or institution. The API provides flexibility in how you interact with your records. As an individual you might want to programmatically access your items or upload a really big file. If you manage an institution’s repository, you may want to programmatically search your repository, access records in bulk, or manage users, among many other possibilities.
The Figshare API documentation provides all the technical information needed to interact with the API and it also gives helpful hints. Our API documentation lives at https://docs.figshare.com/.
The documentation is more than just something to read through. You can interact with the API right from that page. Entering your API token (learn how to get one) in the top left will allow you to use more of the API features, but for the endpoints that return public information, no token is necessary. An endpoint is just a URL address that can contain query information. If you access an endpoint using your bowser, you will see the JSON formatted information as a (very basic) webpage. You can access some endpoints directly in the API documentation and results appear as a popup in the page.
In the documentation, a metadata record is referred to as an ‘Article’. Articles, Collections, and Projects all have separate endpoints and each returns information specific to each type of object. There are also endpoints specific to working with files. Output is all in JSON format but the OAI-PMH endpoint can return records formatted in several different ways.
By the way, the sources for these pages are publicly hosted on github at figshare/user_documentation and it's open for contributions. If you feel you can improve anything, fix a mistake, expand on a topic, feel free to open up a pull request.
To see all the metadata, including custom fields, for a single item, copy the item id from the end of the item’s URL and paste it into the box for Articles -> Public article -> View article details. The API returns the metadata in JSON format for you to view. This includes the same information available at the Figshare URL for the item as well as additional information. You can copy and paste the result into a program of your choice.
Note: There are also endpoints to retrieve metadata for Projects and Collections.
You can get a JSON formatted list of the basic metadata for all the articles you own by going to the Articles -> Private articles. Make sure you enter your token in the upper left box. Change the page size parameter to be more than the number of items you have in your account. You can copy and paste the result into a program of your choice.
You can now add an image for a thumbnail through the metadata entry form. You can also use the API to select a specific file that is part of your item to be the thumbnail. Use the Articles -> Article version update thumb to choose what file is previewed.
**For accounts not managed by an HR feed or SSO system**
This only applies to accounts created outside of an HR feed or SSO system. To update an account’s user’s group affiliation or make them active/inactive use the Institutions -> Update institution account end point. You can also create new accounts using Institution -> Create new institution account, but keep in mind that the new account will not sync if your institution also uses an HR feed or creating accounts at first login. Whether you use an HR feed or not, you can see all the accounts you have administrator rights for using Institutions -> Private institution accounts list.
You can use any programming language/package or method that allows you to interact with an API endpoint. The Figshare documentation includes sample scripts for various languages/methods using the swagger package.
To use the swagger client with Python, you’ll need to download the swagger client package for Python. You can download that by clicking the ‘Other’ link and selecting ‘Python’. Then click the ‘python’ link above the gray box. It will show you a code template you can copy and paste into your script. Then you’ll be on your way!
The following examples demonstrate the steps necessary to complete various tasks. The sample scripts do not use the Swagger package and can be run on your own system with Jupyter Notebook or through Google Colab.
This is useful if you want to see a summary of your own records and their stats.
We’ve made an example Jupyter Notebook using Python that you can run in Google Colab or download. This script does not require the Swagger client.
Note, this will only show statistics for items owned by the account. It will not reflect items where an individual is a co-author.
This is described in the API documentation and there is a sample Python script as well. The process involves:
We’ve made an example Jupyter Notebook based on the script provided in the documentation that you can download, customize to your needs, and start using. This script does not require the Swagger client.
You might want to retrieve all the public metadata in your repository as a spreadsheet. Here are the steps to do this. Note this does not include metadata for collections or projects.
To get all records, you’ll need to set the page size, figure out how many pages will be needed to display all your records, and then make an API call for every page.
We’ve made an example Jupyter Notebook using Python that you can download, customize to your institution, and start using. You can run this in Google Colab but be cognizant of how many records you may be retrieving. This script does not require the Swagger client.
As an administrator you may want a spreadsheet of all published metadata whether it is public or not. You’ll need an API token for this. Note this does not include metadata for collections or projects.
To get all records, you’ll need to set the page size, figure out how many pages will be needed to display all your records, and then make an API call for every page. You can use the user report to see how many records exist.
We’ve made an example Jupyter Notebook using Python that you can download, customize to your institution, and start using. You can run this in Google Colab but be cognizant of how many records you may be retrieving. This script does not require the Swagger client and includes some extra things: adding the record owner name and email, adding the name of the group the record is part of and formatting author names and dates.
This is useful for an admin to create a table to send to an author as part of a report.
We’ve made an example Jupyter Notebook using Python that you can customize to your institution and run in Google Colab, or download. This script does not require the Swagger client.
Harvest some metadata (with existing DOIs if you like) from the source and reformat it for upload to Figshare. Useful for adding records to your repository that point to existing records elsewhere.
We’ve made an example Jupyter Notebook using Python that you can download and customize to your institution. This script does not require the Swagger client.
Besides the statistics dashboards, reporting information can be gathered through the Stats Endpoints. Here is a simple script that can be used as a starting point for working with those endpoints. Please note that statistics within an institutions scope, for example views for the whole repository or group, requires separate authorization. Please email support@figshare.com to get your credentials.
Administrators can also download a spreadsheet of metadata from their repository. The format is json in a CSV so this script will help you reformat it and do some summarization.
These tasks are only the beginning of what you can do with the Figshare API. For more complex examples please see this GitHub pages site. We hope you feel empowered to build tools that will make your workflows more efficient and give you insight into your repository content and use. Please share what you learn with us and others!
The University of Sheffield created a custom frontend to customise the look and feel of their repository and to implement some additional features using the API. Find out more about their process in the webinar available below.
Monash University used the API to migrate content, including their theses, into their Figshare repository. Find out more about their migration in the case study below.
Can’t find your answer here, check the community discussion or raise a support ticket.
Share this article:
