AO3 Tag Stats API

The Tag Stats API is a tool we're building for programmers and fandom analysts to get data from Archive Of Our Own (AO3), and use it in their own project. The data visualisations on the homepage are an example of what you can do with the resulting dataset.

API usage

The API endpoint: http://fandomstats.org/api/v1.0/stats?tag_id={TAG1}

Tags should be in UTF8, optionally urlencoded:

  • Fluff
  • Harry Potter or Harry%20Potter
  • James "Bucky" Barnes or James%20%22Bucky%20%22Barnes

Please be aware that the API can still return (incorrect) values even for badly encoded strings.

To use multiple tags, pass the additional ones as other_tag_names[] param, e.g. http://fandomstats.org/api/v1.0/stats?tag_id={TAG1}&other_tag_names[]={TAG2}&other_tag_names[]={TAG3}

The API is intended for personal/academic use only.

So, how does it work?

The purpose of the API is to make it easy to fetch and display basic stats about any type of AO3 tag. For example, let’s say you want to know more about how any of the following types tags are used:

  • A fandom tag: “Teen Wolf (TV)”
  • A character tag: “Rey (Star Wars)”
  • A relationship tag: “Fox Mulder/Dana Scully”
  • A rating tag: “Mature”
  • A relationship category tag: “F/F”
  • A warning tag: “Graphic Depictions Of Violence”
  • A freeform (additional) tag: “Angst”

You pass the AO3 tag to the API (for example through a HTML field, like here)...

Go

… and we return to you data about how that tag is used on AO3, in JSON format.

Wait, what is this?!

Right now, we’re simply returning to you the same numbers that you’d see in the AO3 Sort & Filter sidebar if you clicked on the tag on AO3 - but without having to record the numbers by hand every time you want to check a tag, and in a format ready to be processed further.

What will it become?

In one word... "more".

  • More visualisations. We want to gradually add new graphs and experiment with ways to display the available data.
  • More kinds of data. There is much more we could be getting out of AO3, things like median hits and median kudos for a tag.
  • More control (both on the homepage and through the API). We want to offer granular filtering of fics, the same way the AO3 website does. Get fic counts just for a certain category within a tag, exclude a character, etc. etc.
  • Provide other fandom data-related information and tools elsewhere on the site. Right now, you can see our AO3 Bookmark Viewer as one such example.

How can I use the existing API -- or help develop it further?

This project is very much a WIP right now. If you want to use our existing Python scripts, the API itself, or help develop the API or the site further, please contact us.

Changelog

2019/12/01 - Updated the warning key to archive_warning following AO3 markup change.

×