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:
  1. Information about the pagination is included in the Link header
  2. Page numbering is 1-based
  3. 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.

Elixir

Python