ACMI public API

Getting started

If you'd prefer to download the entire ACMI Collection, pop down to the Data Dump section. Else, read on.

The ACMI public API is a structured way for you to access the public data in our collection so you can create lovely experiments with ACMI data, images and videos.

To get started, let's have a look at all of the Works in our collection:

https://api.acmi.net.au/works/

You'll notice that what you see is a page of text, but don't worry, a JSON viewer browser plugin will help you make sense of it all. Here's what it looks like when it's formatted nicely using JSON Peep:

You'll notice that you can add something to the end of the URL to get the next page of results: ?page=2

https://api.acmi.net.au/works/?page=2

If you'd like to see a single Work, you can find it here:

https://api.acmi.net.au/works/89182/

Notice the numbers at the end of the URL? 89182 is the ID of the Work you're looking at, a unique number that we use to keep track of all of the collection records. Try changing it to other IDs you found from the Works API.

Search the ACMI API

In the same way you can search for an object in the ACMI Collection on our website, you can do this on our API too by visiting: /search/?query=

https://api.acmi.net.au/search/?query=cat

You might also want to limit your search to a particular API field, like the title: /search/?query=cat&field=title

https://api.acmi.net.au/search/?query=cat&field=title

The search API defaults to showing 20 search results per page. If you'd like to see page 2 of the results: /search/?query=cat&field=title&page=2

https://api.acmi.net.au/search/?query=cat&field=title&page=2

Perhaps 20 results is too many for your liking, you can limit this to anything from 1 to 50, let's try 3: /search/?query=cat&field=title&size=3

https://api.acmi.net.au/search/?query=cat&field=title&size=3

Interactive examples

Documentation is good, but sometimes it's easier to understand concepts with interactive examples. Have a play with these two prototypes we build using Jupyter Notebooks.

For each of the examples, click the Open in Colab link, and then:

• Press all of the Play buttons that appear as you hover over the [ ] symbols next to the code block
• Fill in any fields on the right hand side of the screen that ask you for input
• Change the code, press Play again to reload the blocks of code

Machine dreaming

We thought it might be nice to visualise what a computer makes of our ACMI Collection metadata.

• Code on GitHub
• Open in Colab

Biographies from the Wikipedia API

We have the names and roles of the creators that made the ~45,000 Works in our collection, but we don't have many biographies for each person. So let's use the ACMI Public API and the Wikipedia API to find some.

• Code on GitHub
• Open in Colab

Sample output:

• ACMI API:
  Mad Max (113980)
  API: https://api.acmi.net.au/works/113980/
  Website: https://www.acmi.net.au/works/113980--mad-max/
  Creators: George Miller
  
• Wikipedia API:
  Matched George Miller (66844) to WikiData: George Miller (Q446960) - Australian filmmaker and former physician
  Wikidata: https://www.wikidata.org/wiki/Q446960
  Wikipedia: https://en.wikipedia.org/wiki/George_Miller_(filmmaker)
  Wikipedia extract: George Miller (born 3 March 1945) is an Australian film director, producer, screenwriter, and physician. He is best known for his Mad Max franchise, whose second installment, Mad Max 2, and fourth, Fury Road, have been hailed as two of the greatest action films of all time, with Fury Road winning six Academy Awards. Miller is very diverse in genre and style as he also directed the biographical medical drama Lorenzo's Oil, the dark fantasy The Witches of Eastwick, the Academy-Award winning animated film Happy Feet, produced the family friendly fantasy adventure Babe and directed the sequel Babe: Pig in the City. Miller is a co-founder of the production houses Kennedy Miller Mitchell, formerly known as Kennedy Miller, and Dr. D Studios. His younger brother Bill Miller and Doug Mitchell have been producers on almost all the films in Miller's later career, since the death of his original producing partner Byron Kennedy. In 2006, Miller won the Academy Award for Best Animated Feature for Happy Feet (2006). He has been nominated for five other Academy Awards: Best Original Screenplay in 1992 for Lorenzo's Oil, Best Picture and Best Adapted Screenplay in 1995 for Babe, and Best Picture and Best Director for Fury Road in 2015.
  IMDB person: https://www.imdb.com/name/nm0004306/
  TMDB person: https://www.themoviedb.org/person/20629
  Image: https://upload.wikimedia.org/wikipedia/commons/1/18/George_Miller_-_Happy_Feet_2.jpg
  VIAF ID: 17273086
  Library of Congress authority ID: no88004808
  WorldCat Identities ID: lccn-no88004808

Open API

We've documented the Open API specification that our ACMI API adheres to over at Swagger:
app.swaggerhub.com/apis-docs/acmidev/acmi/1.0#/

Developer API

Our API runs on a Flask server, which you can run on your own computer. To get started:

• Install Docker desktop
• Clone our API repository: github.com/acmilabs/acmi-api
• Run: cd development and then docker-compose up --build
• Visit your local copy of the API at: http://localhost:8081

If you have suggestions for new features or bug fixes, we'd love to hear from you.

Downloading a full set of metadata

ACMI Collection data can also be downloaded as a single folder or file for easy use in data visualisation tools or for integration into union catalogues and digital humanities toolkits.

To download the text metadata:

• Clone the ACMI-api code repository: github.com/acmilabs/acmi-api
• Find all ~42,500 JSON files in the /app/json/ folder
• Find a TSV (tab separated values) spreadsheet with ~42,500 rows of collection metadata in /app/tsv/ folder

License

Collection metadata is is released under the most open license available - Creative Commons Zero. This brings the data in line with other releases from Europeana, Smithsonian,, Tate, MOMA, and Digital Public Library of America (DPLA) and offers the most compatibility and clarity of use for international users. This data does not include any images or video content.