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!