Overview

Introduction Current Version Authentication Pagination Rate Limiting Caching Versioning

Resources

Root Books Characters Houses

Libraries

Elixir GraphQL Haskell Node Python Ruby Swift

Documentation

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 "http://www.anapioficeandfire.com/api/characters?page=1&pageSize=10"

Here's the link header in the response:

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

The possible values in the link response header are:

Name	Description
next	The link to the next page of results.
prev	The link to the previous page of results.
first	The link to the first page of results.
last	The link to the 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

To help our server and your client we provide a few ways for you to use caching. 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"

We advice you to use the above mentioned caching strategies, this will increase the speed of your client as well as save us bandwidth.

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 "http://www.anapioficeandfire.com/api"

Example response:

{
  "books": "http://www.anapioficeandfire.com/api/books",
  "characters": "http://www.anapioficeandfire.com/api/characters",
  "houses": "http://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 that uniquely identifies this book. The format used is ISBN-13.
authors	array of strings	An array of names of the authors that wrote this book.
numberOfPages	integer	The number of pages in this book.
publisher	string	The company that published this book.
country	string	The country which this book was published in.
mediaType	string	The type of media this book was released in. Possible values are: Hardback, Hardcover, GraphicNovel and Paperback.
released	date	The date, in ISO 8601 format, which this book was released
characters	array of string	An array of Character resource URLs that has been in this book.
povCharacters	array of string	An array of Character resource URLs that has had a POV-chapter in this book.

List all books

Example request:

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

Example response:

[
  {
    "url": "http://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": [
      "http://www.anapioficeandfire.com/api/characters/2",
      ...
    ],
    "povCharacters": [
      "http://www.anapioficeandfire.com/api/characters/148",
      ...
    ]
  },
  {
    "url": "http://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": [
      "http://www.anapioficeandfire.com/api/characters/2",
      ...
    ],
    "povCharacters": [
      "http://www.anapioficeandfire.com/api/characters/148",
      ...
    ]
  },
  ...
 ]

Filtering books

There is also the possibility to include filter parameters in your request to the http://www.anapioficeandfire.com/api/books endpoint. They are described below.

Usage	Result
?name=name_here	Only books with the given name are included in the response
?fromReleaseDate=date_here	Only books that were released after, or on, the given date are included in the response.
?toReleaseDate=date_here	Only books that were released before, or on, the given date are included in the response.

Get specific book

Example request:

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

Example response:

{
  "url": "http://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": [
    "http://www.anapioficeandfire.com/api/characters/2",
    ...
  ],
  "povCharacters": [
    "http://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. Possible values are: Female, Male and Unknown.
culture	string	The culture that this character belongs to.
born	string	The year that this person was born
died	string	The year that this person died.
titles	array of strings	The 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	The character resource URL of this character's spouse.
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

Example request:

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

Example response:

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

Filtering characters

There is also the possibility to include filter parameters in your request to the http://www.anapioficeandfire.com/api/characters endpoint. They are described below.

Usage	Result
?name=name_here	Only characters with the given name are included in the response.
?gender=gender_here	Only characters with the given gender are included in the response.
?culture=culture_here	Only characters with the given culture are included in the response.
?born=birth_year_here	Only characters that were born this given year are included in the response.
?died=death_year_here	Only characters that died this given year are included in the response.
?isAlive=true_or_false	Only characters that are alive are included in the response.

Get specific character

Example request:

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

Example response:

{
  "url": "http://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": "http://www.anapioficeandfire.com/api/characters/688",
  "allegiances": [
    "http://www.anapioficeandfire.com/api/houses/10",
    "http://www.anapioficeandfire.com/api/houses/11"
  ],
  "books": [
    "http://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

Example request:

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

Example response:

[
  {
    "url": "http://www.anapioficeandfire.com/api/houses/1",
    "name": "House Algood",
    "region": "The Westerlands",
    "coatOfArms": "A golden wreath, on a blue field with a gold border(Azure, a garland of laurel within a bordure or)",
    "words": "",
    "titles": [],
    "seats": [],
    "currentLord": "",
    "heir": "",
    "overlord": "http://www.anapioficeandfire.com/api/houses/229",
    "founded": "",
    "founder": "",
    "diedOut": "",
    "ancestralWeapons": [],
    "cadetBranches": [],
    "swornMembers": []
  },
  {
    "url": "http://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": "http://www.anapioficeandfire.com/api/characters/298",
    "heir": "http://www.anapioficeandfire.com/api/characters/1922",
    "overlord": "http://www.anapioficeandfire.com/api/houses/285",
    "founded": "",
    "founder": "",
    "diedOut": "",
    "ancestralWeapons": [],
    "cadetBranches": [],
    "swornMembers": [
      "http://www.anapioficeandfire.com/api/characters/1301",
      ...
    ]
  },
  ...
]

Filtering houses

There is also the possibility to include filter parameters in your request to the http://www.anapioficeandfire.com/api/houses endpoint. They are described below.

Usage	Result
?name=name_here	Only houses with the given name are included in the response
?region=region_here	Only houses that belong in the given region are included in the response.
?words=words_here	Only houses that has the given words are included in the response.
?hasWords=true_or_false	Only houses that have words are included in the response.
?hasTitles=true_or_false	Only houses that have titles are included in the response.
?hasSeats=true_or_false	Only houses that have seats are included in the response.
?hasDiedOut=true_or_false	Only houses that are extinct are included in the response.
?hasAncestralWeapons=true_or_false	Only houses that have ancestral weapons are included in the response.

Get specific house

Example request:

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

Example response:

{
  "url": "http://www.anapioficeandfire.com/api/houses/10",
  "name": "House Baelish of Harrenhal",
  "region": "The Riverlands",
  "coatOfArms": "A field of silver mockingbirds, on a green field(Vert, semé of mockingbirds argent)",
  "words": "",
  "titles": [
    "Lord Paramount of the Trident",
    "Lord of Harrenhal"
  ],
  "seats": [
    "Harrenhal"
  ],
  "currentLord": "http://www.anapioficeandfire.com/api/characters/823",
  "heir": "",
  "overlord": "http://www.anapioficeandfire.com/api/houses/16",
  "founded": "299 AC",
  "founder": "http://www.anapioficeandfire.com/api/characters/823",
  "diedOut": "",
  "ancestralWeapons": [],
  "cadetBranches": [],
  "swornMembers": [
    "http://www.anapioficeandfire.com/api/characters/651",
    "http://www.anapioficeandfire.com/api/characters/804",
    "http://www.anapioficeandfire.com/api/characters/823",
    "http://www.anapioficeandfire.com/api/characters/957",
    "http://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

Ruby

game_of_thrones_api by Jason Tam

An API Of Ice And Fire

Documentation

Overview

Resources

Libraries

Documentation

Introduction

Current Version

Authentication

Pagination

Rate Limiting

Caching

Versioning

Resources

Root

Books

List all books

Filtering books

Get specific book

Characters

List all characters

Filtering characters

Get specific character

Houses

List all houses

Filtering houses

Get specific house

Libraries

Elixir

GraphQL

Haskell

Node

Python

Ruby

Swift