An API Of Ice And Fire

All the data from the universe of Ice And Fire you've ever wanted

Documentation

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:

  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 "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.

Elixir

GraphQL

Haskell

Node

Python

Ruby

Swift