Gatsby Source NYTimes Books API Plugin

This GatsyJS source plugin fetches data from the NYTimes Books API

How to install

npm i gatsby-source-nytimes-books-api

How to use

Add a config object to your Gatsby config.js file. You must include an api key obtained from the NYTimes Developer Network

// config.js
{
  resolve: "gatsby-source-nytimes-books-api",
  options: {
    token: 'YOUR_API_KEY', // aqcuire from the NYTimes api site
    type: 'history' // the books data you want access to
    // additional properties for query parameters
  }
}

Available Types

There are six different endpoints available from the NYTimes Books API. Each endpoint has a corresponding type that can be set to pull data from. Below are the available types and the endpoints they correspond to. Check out the NYTimes Books API documentation to learn more about what parameters are available and required to successfully create a query.

lists

Get Best Sellers list. If no date is provided returns the latest list.

date-list

Get Best Sellers list by date.

names-list

Get Best Sellers list names.

overview

Get top 5 books for all the Best Sellers lists for specified date.

reviews

Get book reviews.

history

Get Best Sellers list history.

Passing Query Parameter Values

The books API allows you to query best sellers lists, reviews and books by passing any number of different parameter values. To pass in parameter values to the source plugin, include the parameter name and value as a property of the options object in your config.js file. For example, to use the overview type you can set a publish_date property:

// config.js
{
  resolve: "gatsby-source-nytimes-books-api",
  options: {
    token: 'YOUR_API_KEY',
    type: 'overview'
    published_date: "2018-10-10" // available query param value specified in the NYTimes docs
  }
}

The additional properties in the options object will be used to construct the URL for the API call:

https://api.nytimes.com/svc/books/v3/lists/overview.json?published_date=2018-10-10&api-key=[YOUR_API_KEY]

Use the NYTimes Books API documentation to determine which parameters can be passed.

How to query for data

lists

query {
  allTimesBooksList {
    nodes {
      amazon_product_url
      asterisk
      bestsellers_date
      book_details {
        age_group
        author
        contributor
        contributor_note
        description
        price
        primary_isbn10
        primary_isbn13
        publisher
        title
      }
      dagger
      display_name
      id
      isbns {
        isbn10
        isbn13
      }
      list_name
      published_date
      rank
      rank_last_week
      weeks_on_list
      reviews {
        article_chapter_link
        book_review_link
        first_chapter_link
        sunday_review_link
      }
    }
  }
}

names-list

query {
  allTimesBooksListName {
    nodes {
      display_name
      list_name
      list_name_encoded
      newest_published_date
      oldest_published_date
      updated
      id
    }
  }
}

date-list

Explorer
query 
MyQuery
Docs
query {
  allTimesBooksDateList {
    nodes {
      bestsellers_date
      books {
        age_group
        amazon_product_url
        article_chapter_link
        asterisk
        author
        book_image
        book_image_height
        book_image_width
        book_review_link
        book_uri
        buy_links {
          name
          url
        }
        contributor
        contributor_note
        dagger
        description
        first_chapter_link
        isbns {
          isbn10
          isbn13
        }
        price
        primary_isbn10
        primary_isbn13
        publisher
        rank
        rank_last_week
        sunday_review_link
        title
        weeks_on_list
      }
      display_name
      id
      internal {
        content
        contentDigest
        description
        fieldOwners
        ignoreType
        mediaType
        owner
        type
      }
      list_name
      list_name_encoded
      next_published_date
      normal_list_ends_at
      previous_published_date
      published_date
      published_date_description
    }
    totalCount
  }
}

history

query {
  allTimesBooksBestSellerHistory {
    nodes {
      age_group
      author
      contributor
      contributor_note
      description
      id
      internal {
        content
        contentDigest
        description
        fieldOwners
        ignoreType
        mediaType
        owner
        type
      }
      isbns {
        isbn10
        isbn13
      }
      price
      publisher
      ranks_history {
        asterisk
        bestsellers_date
        dagger
        display_name
        list_name
        primary_isbn10
        primary_isbn13
        published_date
        rank
        weeks_on_list
      }
      reviews {
        article_chapter_link
        book_review_link
        first_chapter_link
        sunday_review_link
      }
      title
    }
  }
}

overview

query {
  allTimesBooksListOverview {
    nodes {
      bestsellers_date
      id
      internal {
        content
        contentDigest
        description
        fieldOwners
        ignoreType
        mediaType
        owner
        type
      }
      lists {
        display_name
        list_id
        list_image
        list_image_height
        list_image_width
        list_name
        list_name_encoded
        updated
      }
      next_published_date
      previous_published_date
      published_date
      published_date_description
    }
  }
}

reviews

query MyQuery {
  allTimesBooksReview {
    nodes {
      book_author
      book_title
      byline
      id
      internal {
        content
        contentDigest
        description
        fieldOwners
        ignoreType
        mediaType
        owner
        type
      }
      isbn13
      publication_dt
      summary
      url
      uri
      uuid
    }
  }
}

How to run tests

npm test

How to develop locally

To work on this plugin locally take a look at Gatsby's documentation on creating a local plugin. Essentially, you will need to include this plugin in a plugins directory of another project to test changes.

How to contribute

Check out the CONTRIBUTING guide to find out how you can get involved!