REST API

Our REST API is following the JSON:API Specification (opens in a new tab).

Endpoints

To access data from the REST API you need to make a GET request to one of the followings endpoints.

Endpoints

Books

/v1/books (list all books)
/v1/characters/:slug (show a specific book)
/v1/characters/:chapters (list all chapters of a specific book)
/v1/characters/:chapters/:slug (show a specific chapter of a specific book)

Characters

/v1/characters (list all characters)
/v1/characters/:slug (show a specific character)

Movies

/v1/movies (list all movies)
/v1/movies/:slug (show a specific movie)

Potions

/v1/potions (list all potions)
/v1/potions/:slug (show a specific potion)

Spells

/v1/spells (list all spells)
/v1/spells/:slug (show a specific spell)

Basic Example

Showing the character "Harry Potter".

curl https://api.potterdb.com/v1/characters/harry-potter

Response

{
  "data": {
    "id": "bc9a37f1-4831-4246-a4a2-ebbce26eff72",
    "type": "character",
    "attributes": {
      "slug": "harry-potter",
      "name": "Harry James Potter",
      "born": "31 July 1980, Godric's Hollow, West Country, England, Great Britain",
      "died": null,
      "gender": "Male",
      "species": "Human",
      "height": null,
      "weight": null,
      "hair_color": "Jet-black",
      "eye_color": "Bright green",
      "skin_color": "Light",
      "blood_status": "Half-blood",
      "marital_status": "Married",
      "nationality": "English",
      "animagus": null,
      "boggart": "Dementor",
      "house": "Gryffindor",
      "patronus": "Stag",
      "alias_names": [
        "The Boy Who Lived",
        "The Chosen One",
        "Undesirable No. 1",
        "Lightning (by Potterwatch)",
        "The Boy Who Lied (by the Daily Prophet)",
        "Gregory Goyle (under disguise of Polyjuice Potion)",
        "Neville Longbottom (the name he told Stanley Shunpike in his third year)",
        "Barny Weasley (under disguise of Polyjuice Potion)",
        "Vernon Dudley (the name he used to disguise his identity from Snatchers)",
        "Albert Runcorn (under disguise of Polyjuice Potion)",
        "Potty (by Peeves and Slytherins)"
      ],
      "family_members": [
        "James Potter I (father) †",
        "Lily J. Potter (née Evans) (mother) †",
        "Ginevra Potter (née Weasley) (wife)",
        "James Potter II (son)",
        "Albus Potter (son)",
        "Lily L. Potter (daughter)",
        "Arthur Weasley (father-in-law)",
        "Molly Weasley (née Prewett) (mother-in-law)",
        "William Weasley (brother-in-law)",
        "Charles Weasley (brother-in-law)",
        "Percy Weasley (brother-in-law)",
        "Fred Weasley (brother-in-law) †",
        "George Weasley (brother-in-law)",
        "Ronald Weasley (brother-in-law)",
        "Fleur Weasley (née Delacour) (sister-in-law)",
        "Audrey Weasley (sister-in-law)",
        "Angelina Weasley (née Johnson) (sister-in-law)",
        "Hermione Granger (sister-in-law)",
        "Victoire Weasley (niece-in-law)",
        "Dominique Weasley (niece-in-law)",
        "Louis Weasley (nephew-in-law)",
        "Molly Weasley II (niece-in-law)",
        "Lucy Weasley (niece-in-law)",
        "Fred Weasley II (nephew-in-law)",
        "Roxanne Weasley (niece-in-law)",
        "Rose Granger-Weasley (niece-in-law)",
        "Hugo Granger-Weasley (nephew-in-law)",
        "Fleamont Potter (paternal grandfather) †",
        "Euphemia Potter (paternal grandmother) †",
        "Mr Evans (maternal grandfather) †",
        "Mrs Evans (maternal grandmother) †",
        "Petunia Dursley (née Evans) (maternal aunt/guardian) †",
        "Vernon Dursley (maternal uncle by marriage/guardian)",
        "Dudley Dursley (maternal first cousin)",
        "Mrs Dursley (maternal first cousin-in-law)",
        "Hardwin Potter (paternal ancestor) †",
        "Iolanthe Potter (née Peverell) (paternal ancestor) †",
        "Linfred of Stinchcombe (paternal ancestor) †",
        "Mr Peverell (paternal ancestor) †",
        "Ignotus Peverell (paternal ancestor) †",
        "Lord Voldemort (paternal distant cousin) †",
        "Delphini (paternal distant cousin)",
        "Potter family",
        "Evans family (maternal family)",
        "Fleamont family (paternal ancestors)",
        "Peverell family (paternal ancestors)",
        "Weasley family (in-laws)",
        "Prewett family (in-laws)",
        "House of Black (in-laws)"
      ],
      "jobs": [
        "Head of British Auror Office (formerly)",
        "Guest lecturer on Defence Against the Dark Arts",
        "Head of the Department of Magical Law Enforcement"
      ],
      "romances": ["Cho Chang (ex-girlfriend)", "Ginevra Potter (wife)"],
      "titles": [
        "Triwizard Champion",
        "Seeker",
        "Quidditch Captain",
        "Master of Death"
      ],
      "wands": [
        "11', Holly, phoenix feather",
        "10¾', Vine, dragon heartstring (temporarily)",
        "10', Blackthorn, unknown core (temporarily)",
        "10', Hawthorn, unicorn hair (temporarily)",
        "15', Elder, thestral hair (temporarily)"
      ],
      "image": "https://static.wikia.nocookie.net/harrypotter/images/9/97/Harry_Potter.jpg",
      "wiki": "https://harrypotter.fandom.com/wiki/Harry_Potter"
    }
  },
  "meta": {
    "copyright": "© 2022 Potter DB API",
    "generated_at": "2022-10-11T09:30:49.628Z"
  },
  "links": {
    "self": "https://api.potterdb.com/v1/characters/harry-potter"
  }
}

Filtering, Sorting and Pagination

You can also filter and paginate the results of collections via query params.

Filtering

We use Ransack to filter the results. Checkout their list of search matchers (opens in a new tab).

Example: Filter the characters by the name Harry

/v1/characters?filter[name_cont_any]=Harry

Sorting

You can also sort the results by a specific field. Add a minus before the field to sort descending.

Example: Sort all characters by name

/v1/characters?sort=name

Pagination

Use page[number=1] and page[size]=5 to paginate the results of the API.

Example: Displaying the results of page 10 with 20 results per page

/v1/characters?page[number=10]&page[size=20]

GraphQL Books