pynytimes

https://pynytimes.michadenheijer.com/
Admin
pynytimes is a Python library that simplifies querying the New York Times API for article metadata...
Tokens:9,970
Snippets:113
Trust Score:5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Example: Fetch Latest NYT Articles in Books Section

Source: https://pynytimes.michadenheijer.com/metadata/latest-articles

An example demonstrating how to fetch the latest articles specifically from the 'nyt' source and the 'books' section.

```python
latest = nyt.latest_articles(
    source = "nyt",
    section = "books"
)
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://pynytimes.michadenheijer.com/popular/most-shared

Perform an HTTP GET request with an 'ask' query parameter to dynamically query the documentation for additional information.

```http
GET https://pynytimes.michadenheijer.com/popular/most-shared.md?ask=<question>
```

--------------------------------

### Example: Fetching Best Sellers Lists

Source: https://pynytimes.michadenheijer.com/popular/best-sellers-lists

Demonstrates fetching best-seller lists for different categories and dates. Includes examples for the default fiction list, a non-fiction list, and a list from a specific past date.

```python
# Get fiction best sellers list
books = nyt.best_sellers_list()

# Get non-fiction best sellers list
books = nyt.best_sellers_list(
    name = "combined-print-and-e-book-nonfiction"
)

# Get best sellers lists from other date
import datetime

books = nyt.best_sellers_list(
    name = "combined-print-and-e-book-nonfiction",
    date = datetime.datetime(2019, 1, 1)
)
```

--------------------------------

### Query Documentation via GET Request

Source: https://pynytimes.michadenheijer.com/popular/top-stories

To get additional information not present on the page, make an HTTP GET request to the page URL with the `ask` query parameter. The question should be specific and self-contained.

```http
GET https://pynytimes.michadenheijer.com/popular/top-stories.md?ask=<question>
```

--------------------------------

### Install pynytimes from GitHub for Development

Source: https://pynytimes.michadenheijer.com/getting-started/installation

Clone the pynytimes repository from GitHub and install it locally. This method is recommended for developers who wish to modify the library's code.

```bash
git clone https://github.com/michadenheijer/pynytimes.git
cd pynytimes
python setup.py install
```

--------------------------------

### Query Documentation with GET Request

Source: https://pynytimes.michadenheijer.com/getting-started

Perform an HTTP GET request to query the documentation dynamically. Use the 'ask' query parameter with a specific, self-contained question in natural language. The response will contain a direct answer and relevant excerpts.

```http
GET https://pynytimes.michadenheijer.com/getting-started.md?ask=<question>
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://pynytimes.michadenheijer.com/metadata/archive-metadata

To get additional information not present on the page, perform an HTTP GET request to the current page URL with the `ask` query parameter. The question should be specific and self-contained.

```http
GET https://pynytimes.michadenheijer.com/metadata/archive-metadata.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://pynytimes.michadenheijer.com/popular/best-sellers-lists

To get information not explicitly present, make an HTTP GET request to the page URL with an `ask` query parameter containing your question. The response will include a direct answer and relevant documentation excerpts.

```http
GET https://pynytimes.michadenheijer.com/popular/best-sellers-lists.md?ask=<question>
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://pynytimes.michadenheijer.com/getting-started/usage

To get additional information not present on the page, perform an HTTP GET request to the documentation URL with the 'ask' query parameter. The question should be specific and in natural language.

```http
GET https://pynytimes.michadenheijer.com/getting-started/usage.md?ask=<question>
```

--------------------------------

### Query Documentation via HTTP GET

Source: https://pynytimes.michadenheijer.com/getting-started/citation

To get additional information not present on the current page, perform an HTTP GET request to the page URL with the 'ask' query parameter. The question should be specific and in natural language.

```http
GET https://pynytimes.michadenheijer.com/getting-started/citation.md?ask=<question>
```

--------------------------------

### Install pynytimes on Linux and Mac

Source: https://pynytimes.michadenheijer.com/getting-started/installation

Use this command to install or upgrade pynytimes on Linux and macOS systems using pip.

```bash
pip install --upgrade pynytimes
```

--------------------------------

### Query Documentation Dynamically

Source: https://pynytimes.michadenheijer.com/search/book-reviews

To get additional information not directly on the page, perform an HTTP GET request with the `ask` query parameter. The question should be specific and self-contained.

```http
GET https://pynytimes.michadenheijer.com/search/book-reviews.md?ask=<question>
```

--------------------------------

### Query documentation dynamically

Source: https://pynytimes.michadenheijer.com/getting-started/installation

Perform an HTTP GET request to query the documentation dynamically by appending the 'ask' query parameter with your question.

```http
GET https://pynytimes.michadenheijer.com/getting-started/installation.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://pynytimes.michadenheijer.com/advanced-usage

Perform an HTTP GET request on the current page URL with the 'ask' query parameter to get dynamic answers to your questions. The question should be specific and self-contained. Use this when the answer is not explicitly present, for clarification, or to retrieve related documentation.

```http
GET https://pynytimes.michadenheijer.com/advanced-usage.md?ask=<question>
```

--------------------------------

### Install pynytimes on Windows

Source: https://pynytimes.michadenheijer.com/getting-started/installation

Use this command to install or upgrade pynytimes on Windows systems using the python -m pip command.

```shell
python -m pip install --upgrade pynytimes
```

--------------------------------

### Example Article Search with Parameters

Source: https://pynytimes.michadenheijer.com/search/article-search

Demonstrates a comprehensive article search using various parameters including query, date range, and multiple search options like sorting, sources, news desk, type of material, and keywords for body and headline.

```python
import datetime

articles = nyt.article_search(
    query = "Obama", # Search for articles about Obama
    results = 30, # Return 30 articles
    # Search for articles in January and February 2019
    dates = {
        "begin": datetime.datetime(2019, 1, 31),
        "end": datetime.datetime(2019, 2, 28)
    },
    options = {
        "sort": "oldest", # Sort by oldest options
        # Return articles from the following four sources
        "sources": [
            "New York Times",
            "AP",
            "Reuters",
            "International Herald Tribune"
        ],
        # Only get information from the Politics desk
        "news_desk": [
            "Politics"
        ],
        # Only return News Analyses
        "type_of_material": [
            "News Analysis"
        ],
        # The article text should contain either the word
        # "Obamacare" or "healthcare"
        "body": [
            "Obamacare",
            "healthcare"
        ],
        # Headline should contain "bill", "costs over", or "victory"
        "headline": [
            "bill",
            "costs over",
            "victory"
        ]
    }
)
```

--------------------------------

### Dynamic Documentation Query

Source: https://pynytimes.michadenheijer.com/metadata/latest-articles

Perform an HTTP GET request with an 'ask' query parameter to dynamically query the documentation. Use this for information not explicitly present on the page.

```http
GET https://pynytimes.michadenheijer.com/metadata/latest-articles.md?ask=<question>
```

--------------------------------

### Install a specific older version of pynytimes

Source: https://pynytimes.michadenheijer.com/getting-started/installation

Install a specific older version of pynytimes, such as 0.7.0, which may be required for compatibility with older Python versions.

```bash
pip install --upgrade pynytimes==0.7.0
```

--------------------------------

### Dynamically Query Documentation

Source: https://pynytimes.michadenheijer.com/other/tags

To get more information not present on the page, perform an HTTP GET request to the current page URL with an 'ask' query parameter containing your question.

```http
GET https://pynytimes.michadenheijer.com/other/tags.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://pynytimes.michadenheijer.com/search

Perform an HTTP GET request on the current page URL with the `ask` query parameter to dynamically query the documentation. Use this when the answer is not explicitly present, for clarification, or to retrieve related sections.

```http
GET https://pynytimes.michadenheijer.com/search.md?ask=<question>
```

--------------------------------

### Querying Documentation Dynamically

Source: https://pynytimes.michadenheijer.com/advanced-usage/automatic-connection

Perform an HTTP GET request with the 'ask' query parameter to dynamically query the documentation. This is useful for retrieving specific information not explicitly present on the page.

```http
GET https://pynytimes.michadenheijer.com/advanced-usage/automatic-connection.md?ask=<question>
```

--------------------------------

### Get Top Stories

Source: https://pynytimes.michadenheijer.com/popular/top-stories

Retrieves a list of top stories. You can optionally specify a section to get stories from a particular category.

```APIDOC
## Get Top Stories

### Description
Loads all the top stories. Optionally, you can specify a section to retrieve top stories from a specific category.

### Method
```python
NYTAPI.top_stories(section=None)
```

### Parameters
#### Query Parameters
- **section** (str) - Optional - Get Top Stories from a specific section. Possible values include: `arts`, `automobiles`, `books`, `business`, `fashion`, `food`, `health`, `home`, `insider`, `magazine`, `movies`, `national`, `nyregion`, `obituaries`, `opinion`, `politics`, `realestate`, `science`, `sports`, `sundayreview`, `technology`, `theater`, `tmagazine`, `travel`, `upshot`, and `world`.

### Request Example
```python
top_stories = nyt.top_stories()

# Get all the top stories from a specific category
top_science_stories = nyt.top_stories(section = "science")
```

### Response
#### Success Response (200)
- **stories** (list) - A list of top stories. Each story is an object containing details like title, abstract, URL, etc.

#### Response Example
```json
{
  "stories": [
    {
      "title": "Example Top Story Title",
      "abstract": "This is an abstract of the top story.",
      "url": "https://www.nytimes.com/example-story"
    }
  ]
}
```
```

--------------------------------

### Query Documentation with `ask` Parameter

Source: https://pynytimes.michadenheijer.com/advanced-usage/close-connection

Perform an HTTP GET request on the current page URL with the `ask` query parameter to dynamically query the documentation. Use this when the answer is not explicitly present, for clarification, or to retrieve related documentation sections.

```http
GET https://pynytimes.michadenheijer.com/advanced-usage/close-connection.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://pynytimes.michadenheijer.com/other

Perform an HTTP GET request to the current page URL with the `ask` query parameter to dynamically query the documentation. The question should be specific and self-contained. Use this when the answer is not explicitly present, for clarification, or to retrieve related documentation.

```http
GET https://pynytimes.michadenheijer.com/other.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://pynytimes.michadenheijer.com/popular

Perform an HTTP GET request to the current page URL with the `ask` query parameter to dynamically query the documentation. Use this when the answer is not explicitly present, for clarification, or to retrieve related sections.

```http
GET https://pynytimes.michadenheijer.com/popular.md?ask=<question>
```

--------------------------------

### Query Documentation Dynamically

Source: https://pynytimes.michadenheijer.com/metadata

Use this method to query documentation dynamically when information is not explicitly present. Perform an HTTP GET request on the current page URL with the 'ask' query parameter.

```http
GET https://pynytimes.michadenheijer.com/metadata.md?ask=<question>
```

--------------------------------

### Get All Available Sections

Source: https://pynytimes.michadenheijer.com/metadata/latest-articles

Retrieve a list of all available article sections. This is useful for filtering articles by section.

```python
sections = nyt.section_list()
```

--------------------------------

### Get All Best Sellers Lists

Source: https://pynytimes.michadenheijer.com/popular/best-sellers-lists

Retrieves all available best sellers lists.

```APIDOC
## Get All Best Sellers Lists

### Description
Retrieves all available best sellers lists.

### Method
```python
nyt.best_sellers_lists()
```

### Example
```python
lists = nyt.best_sellers_lists()
```
```

--------------------------------

### Get Article Metadata

Source: https://pynytimes.michadenheijer.com/metadata/article-metadata

Retrieves all metadata for a specified article URL.

```APIDOC
## Get Article Metadata

### Description
Retrieves all metadata for a specified article URL.

### Method
```python
NYTAPI.article_metadata(url)
```

### Parameters
#### Path Parameters
- **url** (str) - Required - URL of the article

### Request Example
```python
metadata = nyt.article_metadata(
    url = "https://www.nytimes.com/2019/10/20/world/middleeast/erdogan-turkey-nuclear-weapons-trump.html"
)
```

### Response
#### Success Response (200)
- **metadata** (dict) - A dictionary containing the article's metadata.
```

--------------------------------

### Search Movie Reviews with Options and Dates

Source: https://pynytimes.michadenheijer.com/search/movie-reviews

Example of how to search for movie reviews using a specific keyword, reviewer, and date ranges for both opening and publication dates. Ensure datetime objects are used for date parameters.

```python
import datetime

reviews = nyt.movie_reviews(
    keyword = "Green Book",
    options = {
        "order": "by-opening-date",
        "reviewer": "A.O. Scott",
        "critics_pick": False
    },
    dates = {
        "opening_date_start": datetime.datetime(2017, 1, 1),
        "opening_date_end": datetime.datetime(2019, 1, 1),
        "publication_date_start": datetime.datetime(2017, 1, 1),
        "publication_date_end": datetime.datetime(2019, 1, 1)
})
```

--------------------------------

### Search Book Reviews by Author, ISBN, or Title

Source: https://pynytimes.michadenheijer.com/search/book-reviews

Examples demonstrating how to retrieve book reviews using the `book_reviews` function. You must provide either the author, ISBN, or title.

```python
# Get reviews by author (first and last name)
reviews = nyt.book_reviews(author = "George Orwell")
```

```python
# Get reviews by ISBN
reviews = nyt.book_reviews(isbn = 9780062963673)
```

```python
# Get book reviews by title
reviews = nyt.book_reviews(title = "Becoming")
```

--------------------------------

### Get All Best Sellers Lists Names

Source: https://pynytimes.michadenheijer.com/popular/best-sellers-lists

Retrieve a list of all available best-seller list names. This is useful for discovering which lists can be queried.

```python
lists = nyt.best_sellers_lists()
```

--------------------------------

### Load Most Viewed Articles

Source: https://pynytimes.michadenheijer.com/popular/most-viewed

Call the most_viewed method to get articles from the last day. The `days` parameter defaults to 1.

```python
NYTAPI.most_viewed(days=1)
```

--------------------------------

### Get Latest Articles Metadata

Source: https://pynytimes.michadenheijer.com/metadata/latest-articles

Call the latest_articles method to retrieve metadata for articles. You can filter by source and section.

```python
NYTAPI.latest_articles(source=None, section=None)
```

--------------------------------

### Get Article Metadata

Source: https://pynytimes.michadenheijer.com/metadata/article-metadata

Call the article_metadata function with the URL of the article to retrieve its metadata. The URL parameter is required and must be a string.

```python
NYTAPI.article_metadata(url)
```

```python
metadata = nyt.article_metadata(
    url = "https://www.nytimes.com/2019/10/20/world/middleeast/erdogan-turkey-nuclear-weapons-trump.html"
)
```

--------------------------------

### Get Most Emailed Articles (Last Day)

Source: https://pynytimes.michadenheijer.com/popular/most-shared

Retrieve the most emailed articles from the last day by specifying days=1 and method="email".

```python
most_shared = myt.most_shared(
    days = 1,
    method = "email"
)
```

--------------------------------

### Get Most Viewed Articles Over Specific Days

Source: https://pynytimes.michadenheijer.com/popular/most-viewed

Retrieve the most viewed articles for the last 7 or 30 days by specifying the `days` parameter. The default is 1 day.

```python
most_viewed = nyt.most_viewed()

# Get most viewed articles of last 7 or 30 days
most_viewed = nyt.most_viewed(days = 7)
most_viewed = nyt.most_viewed(days = 30)
```

--------------------------------

### Get Most Shared Articles to Facebook (Last 7 Days)

Source: https://pynytimes.michadenheijer.com/popular/most-shared

Retrieve articles most shared to Facebook over the last 7 days by setting days=7 and method="facebook".

```python
most_shared = nyt.most_shared(
    days = 7,
    method = "facebook"
)
```

--------------------------------

### Get Most Shared Articles to Facebook (Last 30 Days)

Source: https://pynytimes.michadenheijer.com/popular/most-shared

Retrieve articles most shared to Facebook over the last 30 days by setting days=30 and method="facebook".

```python
most_shared = nyt.most_shared(
    days = 30,
    method = "facebook"
)
```

--------------------------------

### Initialize NYTAPI with API Key

Source: https://pynytimes.michadenheijer.com/getting-started/usage

Instantiate the NYTAPI class by providing your New York Times API key. Ensure your API key is kept secure and not committed directly into version control.

```python
nyt = NYTAPI("Your API key", parse_dates=True)
```

--------------------------------

### Import pynytimes Library

Source: https://pynytimes.michadenheijer.com/getting-started/usage

Import the NYTAPI class from the pynytimes library to begin using its functionalities.

```python
from pynytimes import NYTAPI
```

--------------------------------

### Automatic Connection with 'with' Statement

Source: https://pynytimes.michadenheijer.com/advanced-usage/automatic-connection

Use the 'with' statement to automatically close the connection after use. This ensures proper resource management without manual closing.

```python
with NYTAPI("Your API Key", parse_dates=True) as nyt:
    nyt.most_viewed()
```

--------------------------------

### Load Archive Metadata by Date

Source: https://pynytimes.michadenheijer.com/metadata/archive-metadata

Use this function to load all metadata for a specific month. Note that this loads a large JSON file and may take a while to complete. The `date` parameter requires a `datetime.datetime` object.

```python
NYTAPI.archive_metadata(date)
```

```python
import datetime

data = nyt.archive_metadata(
    date = datetime.datetime(2019, 1, 1)
)
```

--------------------------------

### Load a Specific Best Seller List

Source: https://pynytimes.michadenheijer.com/popular/best-sellers-lists

Call this function to retrieve a specific best-seller list by name. The `name` parameter specifies the list, and `date` can be used to fetch data from a past date. Defaults to the combined print and e-book fiction list for the current date if not specified.

```python
NYTAPI.best_sellers_list(name="combined-print-and-e-book-fiction", date=None)
```

--------------------------------

### Load Top Stories - PyNytimes

Source: https://pynytimes.michadenheijer.com/popular/top-stories

Use this function to retrieve all top stories. The `section` parameter is optional and accepts a string to filter stories by a specific category.

```python
NYTAPI.top_stories(section=None)
```

```python
top_stories = nyt.top_stories()

# Get all the top stories from a specific category
top_science_stories = nyt.top_stories(section = "science")
```

--------------------------------

### NYTAPI.latest_articles

Source: https://pynytimes.michadenheijer.com/metadata/latest-articles

Loads metadata of the latest articles. Allows filtering by source and section.

```APIDOC
## NYTAPI.latest_articles

### Description
Loads metadata of the latest articles. Allows filtering by source and section.

### Method
```python
NYTAPI.latest_articles(source=None, section=None)
```

### Parameters
#### Query Parameters
- **source** (str) - Optional - Source of article (`all`, `nyt` and `inyt`). Default is `"all"`.
- **section** (str) - Optional - Section of articles. You can find all possible sections using `sections = nyt.section_list()`.

### Example
```python
latest = nyt.latest_articles(
    source = "nyt",
    section = "books"
)
```
```

--------------------------------

### Load Most Shared Articles

Source: https://pynytimes.michadenheijer.com/popular/most-shared

Call the most_shared method to retrieve articles. Defaults to the last day and email sharing.

```python
NYTAPI.most_shared(days=1, method="email")
```

```python
most_shared = nyt.most_shared()
```

--------------------------------

### Load Best Seller List

Source: https://pynytimes.michadenheijer.com/popular/best-sellers-lists

Retrieves a specific best sellers list by name and optionally by date. Defaults to the 'combined-print-and-e-book-fiction' list for the current date if no parameters are provided.

```APIDOC
## Load Best Seller List

### Description
Retrieves a specific best sellers list by name and optionally by date. Defaults to the 'combined-print-and-e-book-fiction' list for the current date if no parameters are provided.

### Method
```python
NYTAPI.best_sellers_list(name: str = "combined-print-and-e-book-fiction", date: datetime.datetime = None)
```

### Parameters
#### Query Parameters
- **name** (str) - Optional - Name of best sellers list. Defaults to "combined-print-and-e-book-fiction".
- **date** (datetime.datetime) - Optional - Date of best sellers list. Defaults to Today.

### Example
```python
# Get fiction best sellers list
books = nyt.best_sellers_list()

# Get non-fiction best sellers list
books = nyt.best_sellers_list(
    name = "combined-print-and-e-book-nonfiction"
)

# Get best sellers lists from other date
import datetime

books = nyt.best_sellers_list(
    name = "combined-print-and-e-book-nonfiction",
    date = datetime.datetime(2019, 1, 1)
)
```
```

--------------------------------

### Load Archive Metadata

Source: https://pynytimes.michadenheijer.com/metadata/archive-metadata

Loads all metadata for a given month. This function retrieves a large JSON file, so expect a delay.

```APIDOC
## Load Archive Metadata

### Description
Loads all metadata for a specific month. Note: This operation retrieves a large JSON file (~20 MB), which may take a considerable amount of time to complete.

### Method
`NYTAPI.archive_metadata(date)`

### Parameters
#### Path Parameters
- **date** (datetime.datetime) - Required - The specific date representing the month for which to load all metadata.

### Request Example
```python
import datetime

data = nyt.archive_metadata(
    date = datetime.datetime(2019, 1, 1)
)
```

### Response
#### Success Response (200)
- **data** (JSON) - The loaded metadata for the specified month.
```

--------------------------------

### Filter Sports Articles by Location

Source: https://pynytimes.michadenheijer.com/search/article-search

Use the 'fq' option to filter articles by news desk and geographic location. Ensure correct syntax for combining filters and specifying locations.

```python
# Get all sports articles from New York City
articles = nyt.article_search(options={
    "fq": "news_desk:(Sports) AND glocations:(\"NEW YORK CITY\")"
})
```

--------------------------------

### BibTeX Citation for pynytimes

Source: https://pynytimes.michadenheijer.com/getting-started/citation

Use this BibTeX entry when citing the pynytimes library in your academic work. Ensure you replace '[CITATION VERSION]' and '[CITATION YEAR]' with the appropriate values.

```latex
@software{Den_Heijer_pynytimes_2023,
    author = {Den Heijer, Micha},
    license = {MIT},
    title = {{pynytimes}},
    url = {https://github.com/michadenheijer/pynytimes},
    version = {[CITATION VERSION]},
    year = {[CITATION YEAR]},
    doi = {10.5281/zenodo.7821090}
}
```

--------------------------------

### Book Reviews Function Signature

Source: https://pynytimes.michadenheijer.com/search/book-reviews

This is the signature for the `book_reviews` function. It accepts optional author, ISBN, or title parameters.

```python
NYTAPI.book_reviews(author=None, isbn=None, title=None)
```

--------------------------------

### Article Search Method

Source: https://pynytimes.michadenheijer.com/search/article-search

Searches for articles matching the provided query and filters. Allows specifying date ranges, sorting, sources, news desks, material types, and content keywords.

```APIDOC
## article_search(query=None, dates=None, options=None, results=10)

### Description
Searches for articles based on a query and various filtering options.

### Parameters
#### Query Parameters
- **query** (str) - Optional - The search term for articles.
- **results** (int) - Optional - The number of results to return (must be a multiple of 10).
- **dates** (dict) - Optional - A dictionary to specify the date range for the search. See details below.
- **options** (dict) - Optional - A dictionary for additional search options. See details below.

#### `dates` Dictionary Parameters
- **begin** (datetime.datetime or datetime.date) - Optional - The start date for the search.
- **end** (datetime.datetime or datetime.date) - Optional - The end date for the search.

#### `options` Dictionary Parameters
- **sort** (str) - Optional - How to sort the results. Valid options: `oldest`, `newest`, `relevance`.
- **sources** (list) - Optional - A list of sources to filter results by.
- **news_desk** (list) - Optional - A list of news desks to filter results by.
- **type_of_material** (list) - Optional - A list of material types to filter results by.
- **section_name** (list) - Optional - A list of section names to filter results by.
- **subject** (list) - Optional - A list of keywords that must be present in the article's subject.
- **body** (list) - Optional - A list of keywords that must be present in the article's body text.
- **headline** (list) - Optional - A list of keywords that must be present in the article's headline.
- **fq** (str) - Optional - Advanced usage for implementing custom filter queries.

### Example
```python
import datetime

articles = nyt.article_search(
    query = "Obama", 
    results = 30, 
    dates = {
        "begin": datetime.datetime(2019, 1, 31),
        "end": datetime.datetime(2019, 2, 28)
    },
    options = {
        "sort": "oldest", 
        "sources": [
            "New York Times",
            "AP",
            "Reuters",
            "International Herald Tribune"
        ],
        "news_desk": [
            "Politics"
        ],
        "type_of_material": [
            "News Analysis"
        ],
        "body": [
            "Obamacare",
            "healthcare"
        ],
        "headline": [
            "bill",
            "costs over",
            "victory"
        ]
    }
)
```
```

--------------------------------

### Load Most Viewed Articles

Source: https://pynytimes.michadenheijer.com/popular/most-viewed

Retrieves a list of the most viewed articles. You can specify the number of days to look back for the articles.

```APIDOC
## Load Most Viewed Articles

### Description
Retrieves a list of the most viewed articles. You can specify the number of days to look back for the articles.

### Method
```python
NYTAPI.most_viewed(days=1)
```

### Parameters
#### Query Parameters
- **days** (int) - Optional - Get most viewed articles over the last `1`, `7` or `30` days. Defaults to `1`.

### Request Example
```python
most_viewed = nyt.most_viewed()

# Get most viewed articles of last 7 or 30 days
most_viewed = nyt.most_viewed(days = 7)
most_viewed = nyt.most_viewed(days = 30)
```

### Response
(Response details not provided in source)
```

--------------------------------

### Search Book Reviews

Source: https://pynytimes.michadenheijer.com/search/book-reviews

Finds New York Times book reviews by specifying the author, ISBN, or title of the book. You must provide at least one of these parameters.

```APIDOC
## Search Book Reviews

### Description
Finds New York Times book reviews by specifying the author, ISBN, or title of the book. You must provide at least one of these parameters.

### Method
`NYTAPI.book_reviews`

### Parameters
#### Query Parameters
- **author** (str) - Optional - Reviews of books from this author. One of author, isbn, or title must be provided.
- **isbn** (str) - Optional - Reviews of books with this ISBN. One of author, isbn, or title must be provided.
- **title** (str) - Optional - Reviews of books with this title. One of author, isbn, or title must be provided.

### Request Example
```python
# Get reviews by author (first and last name)
reviews = nyt.book_reviews(author = "George Orwell")

# Get reviews by ISBN
reviews = nyt.book_reviews(isbn = 9780062963673)

# Get book reviews by title
reviews = nyt.book_reviews(title = "Becoming")
```

### Response
#### Success Response (200)
- **reviews** (list) - A list of book reviews matching the search criteria.
```

--------------------------------

### Article Search Function Signature

Source: https://pynytimes.michadenheijer.com/search/article-search

This is the function signature for article search. It outlines the available parameters for querying articles.

```python
NYTAPI.article_search(query=None, dates=None, options=None, results=10)
```

--------------------------------

### Query New York Times Tags

Source: https://pynytimes.michadenheijer.com/other/tags

Use `tag_query` to search for tags. Specify the query string and optionally the maximum number of results. The `filter_options` parameter can be used for further refinement.

```python
NYTAPI.tag_query(query, max_results=20, filter_options=None)
```

```python
tags = nyt.tag_query(
    "pentagon",
    max_results = 20
)
```

--------------------------------

### Movie Reviews Search

Source: https://pynytimes.michadenheijer.com/search/movie-reviews

Searches for movie reviews using keywords and various filtering options.

```APIDOC
## movie_reviews

### Description
Searches for movie reviews using keywords and various filtering options.

### Method
```python
NYTAPI.movie_reviews(keyword=None, options=None, dates=None)
```

### Parameters
#### Keyword
- **keyword** (str) - Optional - Reviews of movies with this keyword.

#### Options
- **options** (dict) - Optional - Dictionary of search options.
  - **order** (str) - Optional - How to sort the results (`by-title`, `by-publication-date` or `by-opening-date`).
  - **reviewer** (str) - Optional - Name of the reviewer.
  - **critics_pick** (bool) - Optional - Only return critics' pick if `True`.

#### Dates
- **dates** (dict) - Optional - Dictionary of dates about the review.
  - **opening_date_start** (datetime.datetime) - Optional - Reviews about movies released at or after this date.
  - **opening_date_end** (datetime.datetime) - Optional - Reviews about movies released at or before this date.
  - **publication_date_start** (datetime.datetime) - Optional - Reviews released at or after this date.
  - **publication_date_end** (datetime.datetime) - Optional - Reviews released at or before this date.

### Example
```python
import datetime

reviews = nyt.movie_reviews(
    keyword = "Green Book",
    options = {
        "order": "by-opening-date",
        "reviewer": "A.O. Scott",
        "critics_pick": False
    },
    dates = {
        "opening_date_start": datetime.datetime(2017, 1, 1),
        "opening_date_end": datetime.datetime(2019, 1, 1),
        "publication_date_start": datetime.datetime(2017, 1, 1),
        "publication_date_end": datetime.datetime(2019, 1, 1)
    })
```
```

--------------------------------

### Close Connection

Source: https://pynytimes.michadenheijer.com/advanced-usage/close-connection

Call this method to close the `requests.Session()` connection to the New York Times server. This is an optional step.

```python
nyt.close()
```

--------------------------------

### Filter Articles by Keyword and Exclude Location

Source: https://pynytimes.michadenheijer.com/search/article-search

Construct filter queries to search for specific keywords while excluding certain geographic locations. The '-' operator is used for exclusion.

```python
# Get all articles about Obama, but exclude all
# articles from New York City
articles = nyt.article_search(options={
    "fq": "Obama AND -glocations:(\"NEW YORK CITY\")"
})
```

--------------------------------

### tag_query

Source: https://pynytimes.michadenheijer.com/other/tags

Queries for New York Times tags based on a given query string. Allows for specifying maximum results and filter options.

```APIDOC
## tag_query

### Description
Queries for New York Times tags based on a given query string. Allows for specifying maximum results and filter options.

### Method
```python
NYTAPI.tag_query(query, max_results=20, filter_options=None)
```

### Parameters
#### Path Parameters
- **query** (str) - Required - Tags you're looking for

#### Query Parameters
- **max_results** (int) - Optional - Maximum results you'd like (Default: 20)
- **filter_options** (list) - Optional - Filter options

### Request Example
```python
tags = nyt.tag_query(
    "pentagon",
    max_results = 20
)
```
```

--------------------------------

### Movie Reviews Function Signature

Source: https://pynytimes.michadenheijer.com/search/movie-reviews

This is the function signature for searching movie reviews. It accepts a keyword, options, and dates as parameters.

```python
NYTAPI.movie_reviews(keyword=None, options=None, dates=None)
```

--------------------------------

### NYTAPI.most_shared

Source: https://pynytimes.michadenheijer.com/popular/most-shared

Retrieves a list of the most shared articles based on specified parameters.

```APIDOC
## NYTAPI.most_shared

### Description
Loads most shared articles.

### Method
This is a method call within the NYTAPI library.

### Parameters
#### Query Parameters
- **days** (int) - Optional - Get most viewed articles over the last `1`, `7` or `30` days. Default is `1`.
- **method** (str) - Optional - Method of sharing (`email` or `facebook`). Default is `"email"`.

### Request Example
```python
# Get most emailed articles of the last day
most_shared = nyt.most_shared(
    days = 1,
    method = "email"
)

# Get most shared articles to Facebook of the last 7 days
most_shared = nyt.most_shared(
    days = 7,
    method = "facebook"
)

# Get most shared articles to Facebook of the last 30 days
most_shared = nyt.most_shared(
    days = 30,
    method = "facebook"
)
```

### Response
#### Success Response (200)
- The response will be a list of articles, with details on their sharing metrics. (Specific fields not detailed in source)

#### Response Example
(Response example not provided in source)
```
Tokens:
Raw