Documentation

Overview

Introduction Current Version Authentication Pagination Rate Limiting Caching Versioning

Resources

Libraries

Elixir GraphQL Haskell Node Python R Ruby Swift

Introduction

This documentation will help you familiarise yourself with the API and how to consume the different resources that are available. The documentation provides all information needed to get started and it also has educational examples for all resources.

If you're interested in using a native implementation, please take a look at the Libraries section.

Current Version

The current version of the API is 1.

Authentication

An API of Ice And Fire is an open API. This means that no authentication is required to query the API for data. Since no authentication is required, there is only support for GET-ing data.

Pagination

An API of Ice And Fire provides a lot of data about the world of Westeros. To prevent our servers from getting cranky, the API will automatically paginate the responses. You will learn how to create requests with pagination parameters and consume the response.

Things worth noting:

Information about the pagination is included in the Link header
Page numbering is 1-based
You can specify how many items you want to receive per page, the maximum is 50

Constructing a request with pagination

You specify which page you want to access with the ?page parameter, if you don't provide the ?page parameter the first page will be returned. You can also specify the size of the page with the ?pageSize parameter, if you don't provide the ?pageSize parameter the default size of 10 will be used.

Let's make a request for the first page of characters with a page size of 10. Since we're only interested in the pagination information we provide the -I parameter to say that we only care about the headers.

$ curl -I "https://www.anapioficeandfire.com/api/characters?page=1&pageSize=10"

Here's the link header in the response:



                                    Link: <https://www.anapioficeandfire.com/api/characters?page=2&pageSize=10>; rel="next",
                                    <https://www.anapioficeandfire.com/api/characters?page=1&pageSize=10>; rel="first",
                                    <https://www.anapioficeandfire.com/api/characters?page=214&pageSize=10>; rel="last"

Possible link types:

next - Next page of results
prev - Previous page of results
first - First page of results
last - Last page of results

These links can then be used to navigate to other pages of results.

Rate Limiting

To prevent malicious usage of our API we've a limit on the number of requests a given IP address can make to the API. This limit is set to 20000 requests per day. There should be no reason for hitting the limit if you implement proper caching strategies in your client. If you happen to hit the limit you'll receive a 403 Forbidden on all your requests for the remainder of the 24 hour time period.

Caching

Apart from the standard cache headers such as max-age we also provide a few different ways to ease the load on our servers and your client. Each API response includes the ETag-header and the Last-Modified header. These headers can be used to ask our server if the data has changed or not. If the data has not changed you will receive an empty response body with a 304 Not Modified. If the data has changed you will receive a 200 with the updated data.

To use the ETag, include the following header in your request:

If-None-Match: "your_etag_here"

To use Last-Modified, include the following header in your request:

If-Modified-Since: "date_here"

Versioning

Custom media types are used in An API of Ice And Fire to let consumers choose which version of the data they wish to receive. This is done by adding the following type to the Accept header when you make a request. Note that media types are specific to resources, this allows them to change independently from each other.

Important: If a version is not specified in the request the default version will be used. The default version may change in the future and can thus break the consumer's application. Make sure to always request a specific version in the Accept header as shown in the example below.

You specify a version like so:

application/vnd.anapioficeandfire+json; version=1

Resources

Root

The Root resource contains information about all available resources in the API.

Example request:

$ curl "https://www.anapioficeandfire.com/api"

Example response:

{
    "books": "https://www.anapioficeandfire.com/api/books",
    "characters": "https://www.anapioficeandfire.com/api/characters",
    "houses": "https://www.anapioficeandfire.com/api/houses"
 }

Books

Name	Type	Description
url	string	The hypermedia URL of this resource
name	string	The name of this book
isbn	string	The International Standard Book Number (ISBN-13) that uniquely identifies this book.
authors	array of strings	An array of names of the authors that wrote this book.
numberOfPages	integer	The number of pages in this book.
publiser	string	The company that published this book.
country	string	The country that this book was published in
mediaType	string	The type of media this book was released in.
released	date	The date (ISO 8601) when this book was released.
characters	array of strings	An array of Character resource URLs that has been in this book.
povCharacters	array of strings	An array of Character resource URLs that has had a POV-chapter in this book.

List all books:

$ curl "https://www.anapioficeandfire.com/api/books"

Example response:

[
  {
    "url": "https://www.anapioficeandfire.com/api/books/1",
    "name": "A Game of Thrones",
    "isbn": "978-0553103540",
    "authors": [
      "George R. R. Martin"
    ],
    "numberOfPages": 694,
    "publisher": "Bantam Books",
    "country": "United States",
    "mediaType": "Hardcover",
    "released": "1996-08-01T00:00:00",
    "characters": [
      "https://www.anapioficeandfire.com/api/characters/2",
      ...
    ],
    "povCharacters": [
      "https://www.anapioficeandfire.com/api/characters/148",
      ...
    ]
  },
  {
    "url": "https://www.anapioficeandfire.com/api/books/2",
    "name": "A Clash of Kings",
    "isbn": "978-0553108033",
    "authors": [
      "George R. R. Martin"
    ],
    "numberOfPages": 768,
    "publisher": "Bantam Books",
    "country": "United States",
    "mediaType": "Hardcover",
    "released": "1999-02-02T00:00:00",
    "characters": [
      "https://www.anapioficeandfire.com/api/characters/2",
      ...
    ],
    "povCharacters": [
      "https://www.anapioficeandfire.com/api/characters/148",
      ...
    ]
  },
  ...
 ]

Filtering books

You can also include filter parameters in your request to the books endpoint by including parameters in the query string.

Parameter	Type	Result
name	string	Books with the given name are included in the response
fromReleaseDate	date	Books that were released after, or on, the given date are included in the response.
toReleaseDate	date	Books that were released before, or on, the given date are included in the response.

Get specific book

$ curl "https://www.anapioficeandfire.com/api/books/1"

Example response:

{
  "url": "https://www.anapioficeandfire.com/api/books/1",
  "name": "A Game of Thrones",
  "isbn": "978-0553103540",
  "authors": [
    "George R. R. Martin"
  ],
  "numberOfPages": 694,
  "publisher": "Bantam Books",
  "country": "United States",
  "mediaType": "Hardcover",
  "released": "1996-08-01T00:00:00",
  "characters": [
    "https://www.anapioficeandfire.com/api/characters/2",
    ...
  ],
  "povCharacters": [
    "https://www.anapioficeandfire.com/api/characters/148",
    ...
  ]
}

Characters

A Character is an individual within the Ice And Fire universe.

Name	Type	Description
url	string	The hypermedia URL of this resource
name	string	The name of this character
gender	string	The gender of this character.
culture	string	The culture that this character belongs to.
born	string	Textual representation of when and where this character was born.
died	string	Textual representation of when and where this character died.
titles	array of strings	TThe titles that this character holds.
aliases	array of strings	The aliases that this character goes by.
father	string	The character resource URL of this character's father.
mother	string	The character resource URL of this character's mother.
spouse	string	An array of Character resource URLs that has had a POV-chapter in this book.
allegiances	array of strings	An array of House resource URLs that this character is loyal to.
books	array of strings	An array of Book resource URLs that this character has been in.
povBooks	array of strings	An array of Book resource URLs that this character has had a POV-chapter in.
tvSeries	array of strings	An array of names of the seasons of Game of Thrones that this character has been in.
playedBy	array of strings	An array of actor names that has played this character in the TV show Game Of Thrones.

List all characters:

$ curl "https://www.anapioficeandfire.com/api/characters"

Example response:

[
  {
    "url": "https://www.anapioficeandfire.com/api/characters/1",
    "name": "",
    "culture": "Braavosi",
    "born": "",
    "died": "",
    "titles": [],
    "aliases": [
      "The Daughter of the Dusk"
    ],
    "father": "",
    "mother": "",
    "spouse": "",
    "allegiances": [],
    "books": [
      "https://www.anapioficeandfire.com/api/books/5"
    ],
    "povBooks": [],
    "tvSeries": [],
    "playedBy": []
  },
  {
    "url": "https://www.anapioficeandfire.com/api/characters/2",
    "name": "",
    "culture": "",
    "born": "",
    "died": "",
    "titles": [],
    "aliases": [
      "Hodor"
    ],
    "father": "",
    "mother": "",
    "spouse": "",
    "allegiances": [
      "https://www.anapioficeandfire.com/api/houses/362"
    ],
    "books": [
      "https://www.anapioficeandfire.com/api/books/1",
      ...
    ],
    "povBooks": [],
    "tvSeries": [
      "Season 1",
      "Season 2",
      "Season 3",
      "Season 4"
    ],
    "playedBy": [
      "Kristian Nairn"
    ]
  },
  ...
]

Filtering characters

You can also include filter parameters in your request to the characters endpoint by including parameters in the query string.

Parameter	Type	Result
name	string	Characters with the given name are included in the response.
gender	string	Characters with the given gender are included in the response.
culture	string	Characters with the given culture are included in the response.
born	string	Characters that were born this given year are included in the response.
died	string	Characters that died this given year are included in the response.
isAlive	boolean	Characters that are alive or dead (depending on the value) are included in the response.

Get specific character

$ curl "https://www.anapioficeandfire.com/api/characters/823"

Example response:

{
  "url": "https://www.anapioficeandfire.com/api/characters/823",
  "name": "Petyr Baelish",
  "culture": "Valemen",
  "born": "In 268 AC, at the Fingers",
  "died": "",
  "titles": [
    "Master of coin (formerly)",
    "Lord Paramount of the Trident",
    "Lord of Harrenhal",
    "Lord Protector of the Vale"
  ],
  "aliases": [
    "Littlefinger"
  ],
  "father": "",
  "mother": "",
  "spouse": "https://www.anapioficeandfire.com/api/characters/688",
  "allegiances": [
    "https://www.anapioficeandfire.com/api/houses/10",
    "https://www.anapioficeandfire.com/api/houses/11"
  ],
  "books": [
    "https://www.anapioficeandfire.com/api/books/1",
    ...
  ],
  "povBooks": [],
  "tvSeries": [
    "Season 1",
    "Season 2",
    "Season 3",
    "Season 4",
    "Season 5"
  ],
  "playedBy": [
    "Aidan Gillen"
  ]
}

Houses

A House is a house branch within the Ice And Fire universe.

Name	Type	Description
url	string	The hypermedia URL of this resource
name	string	The name of this house
region	string	The region that this house resides in.
coatOfArms	string	Text describing the coat of arms of this house.
words	string	The words of this house.
titles	array of strings	The titles that this house holds.
seats	array of strings	The seats that this house holds.
currentLord	string	The Character resource URL of this house's current lord.
heir	string	The Character resource URL of this house's heir.
overlord	string	The House resource URL that this house answers to.
founded	string	The year that this house was founded.
founder	string	The Character resource URL that founded this house.
diedOut	string	The year that this house died out.
ancestralWeapons	array of strings	An array of names of the noteworthy weapons that this house owns.
cadetBranches	array of strings	An array of House resource URLs that was founded from this house.
swornMembers	array of strings	An array of Character resource URLs that are sworn to this house.

List all houses:

$ curl "https://www.anapioficeandfire.com/api/houses"

Example response:

[
  {
    "url": "https://www.anapioficeandfire.com/api/houses/1",
    "name": "House Algood",
    "region": "The Westerlands",
    "coatOfArms": "A golden wreath, on a blue field with a gold border",
    "words": "",
    "titles": [],
    "seats": [],
    "currentLord": "",
    "heir": "",
    "overlord": "https://www.anapioficeandfire.com/api/houses/229",
    "founded": "",
    "founder": "",
    "diedOut": "",
    "ancestralWeapons": [],
    "cadetBranches": [],
    "swornMembers": []
  },
  {
    "url": "https://www.anapioficeandfire.com/api/houses/2",
    "name": "House Allyrion of Godsgrace",
    "region": "Dorne",
    "coatOfArms": "Gyronny Gules and Sable, a hand couped Or",
    "words": "No Foe May Pass",
    "titles": [],
    "seats": [
      "Godsgrace"
    ],
    "currentLord": "https://www.anapioficeandfire.com/api/characters/298",
    "heir": "https://www.anapioficeandfire.com/api/characters/1922",
    "overlord": "https://www.anapioficeandfire.com/api/houses/285",
    "founded": "",
    "founder": "",
    "diedOut": "",
    "ancestralWeapons": [],
    "cadetBranches": [],
    "swornMembers": [
      "https://www.anapioficeandfire.com/api/characters/1301",
      ...
    ]
  },
  ...
]

Filtering houses

You can also include filter parameters in your request to the characters endpoint by including parameters in the query string.

Parameter	Type	Result
name	string	Houses with the given name are included in the response
region	string	Houses that belong in the given region are included in the response.
words	string	Houses that has the given words are included in the response.
hasWords	boolean	Houses that have words (or not) are included in the response.
hasTitles	boolean	Houses that have titles (or not) are included in the response.
hasSeats	boolean	Houses that have seats (or not) are included in the response.
hasDiedOut	boolean	Houses that are extinct are included in the response.
hasAncestralWeapons	boolean	Houses that have ancestral weapons (or not) are included in the response.

Get specific house

$ curl "https://www.anapioficeandfire.co/api/houses/10"

Example response:

{
  "url": "https://www.anapioficeandfire.com/api/houses/10",
  "name": "House Baelish of Harrenhal",
  "region": "The Riverlands",
  "coatOfArms": "A field of silver mockingbirds, on a green field",
  "words": "",
  "titles": [
    "Lord Paramount of the Trident",
    "Lord of Harrenhal"
  ],
  "seats": [
    "Harrenhal"
  ],
  "currentLord": "https://www.anapioficeandfire.com/api/characters/823",
  "heir": "",
  "overlord": "https://www.anapioficeandfire.com/api/houses/16",
  "founded": "299 AC",
  "founder": "https://www.anapioficeandfire.com/api/characters/823",
  "diedOut": "",
  "ancestralWeapons": [],
  "cadetBranches": [],
  "swornMembers": [
    "https://www.anapioficeandfire.com/api/characters/651",
    "https://www.anapioficeandfire.com/api/characters/804",
    "https://www.anapioficeandfire.com/api/characters/823",
    "https://www.anapioficeandfire.com/api/characters/957",
    "https://www.anapioficeandfire.com/api/characters/970"
  ]
}

Libraries

There exists helper libraries that will help you consume An API of Ice And Fire in a specific programming language.

Python

anapioficeandfire-python by the author of An API of ice And Fire, Joakim Skoog

R

GoTr by Ava Yang

Ruby

game_of_thrones_api by Jason Tam

Swift

Overview

Introduction Current Version Authentication Pagination Rate Limiting Caching Versioning

Resources

Root Books Characters Houses

Libraries

Elixir GraphQL Haskell Node Python R Ruby Swift