figshare help

How to use the Figshare API

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.

Why the API?

The thing that makes Figshare so great is that it is customizable and 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.

Examples - Simple tasks - no scripting needed!

View an item’s metadata

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.


Get a list of all the items you own

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.


Change the thumbnail preview

You may wish to change what image is previewed in search results and display pages. Use the Articles -> Article version update thumb to choose what file is previewed.


Repository Manager - Manage users

**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.


Tasks that require some scripting

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.


Examples that use scripting

For the Individual User

Get a table of your account’s Items and Collections with views and downloads

This is useful if you want to see a summary of your own records and their stats.

  1. Create a token for your account
  2. Gather basic metadata for items owned by your account
  3. Remove unpublished items
  4. For each item, use the stats API endpoint to get the total views and total downloads
  5. Merge the basic metadata and statistics into one table
  6. Repeat this process for Collections owned by your account
  7. Merge the item and Collection tables

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.

Upload a file via API (useful for very large files)

This is described in the API documentation and there is a sample Python script as well. The process involves:

  1. Creating an item to receive the files
  2. Initiating the upload
  3. Splitting your file into defined chunks (e.g. 10 MB chunks)
  4. Uploading each chunk
  5. Completing the upload

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.

For Repository Administrators

Get all metadata for public items

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.

  1. Use Articles -> Public articles API endpoint to get a JSON file listing basic metadata for all the public items in your repository. For example, this request returns 10 records from University of Loughborough: https://api.figshare.com/v2/articles?institution=2&page_size=10&page=1 

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.

  1. Pull out all the item ids from the JSON file.
  2. For each item id, use the Articles -> Public article -> View article details endpoint to retrieve the detailed metadata record
  3. Add each item’s detailed metadata to one big JSON file.
  4. Convert that to a spreadsheet.

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.


See all metadata for published records (public or embargoed)

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.

  1. Use Articles -> Private articles API endpoint to get a JSON file listing basic metadata for all the items in your repository. As long as your token is from a top level administrator account, this lists basic metadata for all metadata records, including drafts, unpublished items, and published items.

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.

  1. Remove unpublished articles.
  2. For each item id, use the Articles -> Private article -> Article details endpoint to retrieve the detailed metadata record.
  3. Add each item’s detailed metadata to one big JSON file.
  4. Convert that to a spreadsheet

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.


Get a table of an author’s Items and Collections with views and downloads

This is useful for an admin to create a table to send to an author as part of a report.

  1. Search for items by name or ORCID
  2. For each item, use the stats API endpoint to get the total views and total downloads
  3. Merge the basic metadata and statistics into one table
  4. Repeat this process for Collections
  5. Merge the item and Collection tables

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.

These tasks are only the beginning of what you can do with the Figshare API. 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!

Examples from Institutions

University of Sheffield

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

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.


Share this article: