Pagination & search

Page through collections and filter them by name.

Every list endpoint accepts the same three query parameters.

pageinteger
1
Which page to return. Values past the last page are clamped to the last page.
page_sizeinteger
25
How many records per page. Clamped to a maximum of 100.
searchstring
Case-insensitive substring match on the record's title (books, movies) or name (everything else).

Reading meta

Every list response carries a meta object. Use total_pages to drive your loop rather than requesting pages until you get an empty array.

curl "https://hogwarts-api.com/api/characters?page=2&page_size=5"

{
  "data": [ "…5 characters…" ],
  "meta": {
    "page": 2,
    "page_size": 5,
    "total_pages": 1082,
    "total_records": 5410,
    "search": null
  }
}

When search is active, total_records and total_pages describe the filtered set, not the whole collection.

Searching

curl "https://hogwarts-api.com/api/spells?search=charm"
curl "https://hogwarts-api.com/api/creatures?search=dragon"
curl "https://hogwarts-api.com/api/characters?search=weasley&page_size=100"

Search is a plain substring match — search=weasley matches "Ginevra Molly Weasley" because the string appears anywhere in the name. It is not fuzzy, so a typo returns nothing.

Paging through everything

JavaScript
Python
async function fetchAll(collection) {
  const records = [];
  let page = 1;
  let totalPages = 1;

  do {
    const res = await fetch(
      `https://hogwarts-api.com/api/${collection}?page=${page}&page_size=100`,
    );
    const { data, meta } = await res.json();

    records.push(...data);
    totalPages = meta.total_pages;
    page += 1;
  } while (page <= totalPages);

  return records;
}

const spells = await fetchAll('spells');
Quick start
Make your first request in under a minute.
Errors
What the API returns when a request cannot be fulfilled.