Name: The Numbers API: Daily & Weekend Box Office Data
Brand: proapi
SKU: api-proapi-the-numbers
Availability: InStock
Author: API Market

JarX8

# The Numbers API: Box Office Charts & Grosses

## Overview

The Numbers API returns movie business data from The Numbers, the box office site at the-numbers.com, across 5 GET endpoints. Two chart endpoints return the domestic box office for a single day or for a weekend starting on a Friday, and a market endpoint returns the top-grossing movies of a year, optionally in inflation-adjusted dollars. A search endpoint finds movies by title and returns the slug that the details endpoint needs. Chart rows also carry that slug, so you can go from a chart straight to a movie's full record.

It is built for film industry analysts, entertainment journalists, movie data apps, studio and distribution researchers, and students or data scientists modeling box office performance. Chart rows include rank, previous rank, gross, daily and weekly change, theater count, per-theater average, total gross and days in release. Movie details include domestic, international and worldwide box office, DVD and Blu-ray sales, production budget, release details such as MPA rating, running time, genre, source and production companies, and daily, weekend, weekly and per-territory performance.

## Features

*   **5 endpoints**: Daily chart, weekend chart, top-grossing movies by year, movie search and movie details, all plain GET requests that return JSON.
*   **Daily and weekend charts**: Movies reporting grosses for the date, with rank, previous rank, gross, daily and weekly change, theaters, per-theater average, running total and days in release, plus the chart's total box office.
*   **Top-grossing movies by year**: /v1/market/top-grossing-movies returns a year's top earners, in actual or inflation-adjusted dollars.
*   **Movie financials**: Domestic, international and worldwide box office, DVD and Blu-ray sales and production budget for a single movie.
*   **Run performance and territories**: Daily, weekend and weekly performance over a film's run, plus per-territory results where available.
*   **Slug lookups**: /v1/movie/search returns slugs with year, lead cast and director, and chart rows carry the same slugs for /v1/movie/details.
*   **Data source**: Publicly visible box office data from The Numbers (the-numbers.com), with the source page URL on each movie.
*   **Rate limit**: 10 requests/second on the free trial, 300 on pay-as-you-go.

## Use Cases

*   **Box office reporting**: Publish weekend box office top lists with grosses, theater counts and week over week changes from /v1/box-office/weekend-chart.
*   **Industry analysis**: Track a film's daily, weekend and weekly performance and compare its total gross against its production budget.
*   **Historical comparisons**: Rank the top-grossing movies of different years in inflation-adjusted dollars to compare eras fairly.
*   **Movie data apps**: Add budget, domestic and worldwide gross figures to film pages using /v1/movie/search and /v1/movie/details.
*   **International performance**: Use per-territory results and the international gross to see where a film earned its money.
*   **Forecasting and modeling**: Collect daily charts over time to build datasets for opening weekend and lifetime gross predictions.

## Pricing

| Plan | Price | What you get | Rate limit |
|---|---|---|---|
| Free | $0 | 7-day trial with 100 API calls | 10 requests/second |
| PAYG | No monthly fee | US$0.001 per successful call, paid from your API.market wallet | 300 requests/second |

Only successful (2xx) responses count. A lookup for something that does not exist returns `404` and is not billed.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/proapi/the-numbers
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Get daily box office chart

Returns the daily domestic box office chart for a given date.

**Method:** `GET`

**Endpoint:** `/v1/box-office/daily-chart`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `date` | query | Date in Y-m-d format (e.g., 2026-07-13). | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/proapi/the-numbers/v1/box-office/daily-chart?date=2026-10-05" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "date": "2026-10-05",
  "title": "Daily Domestic Box Office Monday, October 5, 2026",
  "totalBoxOffice": 7067506,
  "reportingMovies": 20,
  "movies": [
    {
      "rank": 1,
      "previousRank": 1,
      "label": null,
      "title": "Verity",
      "slug": "Verity-(2026)",
      "url": "https://www.the-numbers.com/movie/Verity-(2026)",
      "gross": 2402236,
      "dailyChange": -66,
      "weeklyChange": null,
      "theaters": 3510,
      "theaterAverage": 684,
      "totalGross": 34433247,
      "daysInRelease": 4
    },
    {
      "rank": 2,
      "previousRank": 2,
      "label": null,
      "title": "Resident Evil",
      "slug": "Resident-Evil-(2026)",
      "url": "https://www.the-numbers.com/movie/Resident-Evil-(2026)",
      "gross": 1223785,
      "dailyChange": -65,
      "weeklyChange": -42,
      "theaters": 3259,
      "theaterAverage": 376,
      "totalGross": 126237519,
      "daysInRelease": 18
    }
  ]
}
```

#### 2. Get weekend box office chart

Returns the weekend domestic box office chart for the weekend starting on a given Friday.

**Method:** `GET`

**Endpoint:** `/v1/box-office/weekend-chart`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `date` | query | Friday the weekend starts on, in Y-m-d format (e.g., 2026-07-10). | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/proapi/the-numbers/v1/box-office/weekend-chart?date=2026-10-02" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "date": "2026-10-02",
  "title": "Weekend Domestic Box Office October 2, 2026",
  "totalBoxOffice": 98690993,
  "reportingMovies": 66,
  "movies": [
    {
      "rank": 1,
      "previousRank": null,
      "label": null,
      "title": "Verity",
      "slug": "Verity-(2026)",
      "url": "https://www.the-numbers.com/movie/Verity-(2026)",
      "gross": 32031011,
      "weeklyChange": null,
      "theaters": 3510,
      "theaterAverage": 9126,
      "totalGross": 32031011,
      "daysInRelease": 3
    },
    {
      "rank": 2,
      "previousRank": 2,
      "label": null,
      "title": "Resident Evil",
      "slug": "Resident-Evil-(2026)",
      "url": "https://www.the-numbers.com/movie/Resident-Evil-(2026)",
      "gross": 12618839,
      "weeklyChange": -45,
      "theaters": 3259,
      "theaterAverage": 3872,
      "totalGross": 125013734,
      "daysInRelease": 17
    }
  ]
}
```

#### 3. Get top-grossing movies

Returns the top-grossing movies of a given year, optionally in inflation-adjusted dollars.

**Method:** `GET`

**Endpoint:** `/v1/market/top-grossing-movies`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `year` | query | Year to get the top-grossing movies for (e.g., 2026). | integer | Yes | - | - |
| `inflation_adjusted` | query | Whether the gross is returned in inflation-adjusted dollars (defaults to false). Example: `false`. | boolean | Yes | `false` | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/proapi/the-numbers/v1/market/top-grossing-movies?year=2025&inflation_adjusted=false" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Response:** the image file itself, not JSON.

#### 4. Search movies

Searches movies by title and returns the slug needed by the movie details endpoint.

**Method:** `GET`

**Endpoint:** `/v1/movie/search`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `q` | query | Search query, at least 3 characters (e.g., "interstellar"). | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/proapi/the-numbers/v1/movie/search?q=avatar" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
[
  {
    "title": "Avatar Aang: The Last Airbender",
    "year": 2026,
    "slug": "Avatar-Aang-The-Last-Airbender-(2026)",
    "url": "https://www.the-numbers.com/movie/Avatar-Aang-The-Last-Airbender-(2026)",
    "leadCast": "Eric Nam, Dave Bautista",
    "director": "Lauren Montgomery",
    "thumbnail": "https://media.the-numbers.com/images/movie-posters/Avatar-Aang-The-Last-Airbender-(2026).jpg",
    "type": "movie"
  },
  {
    "title": "Krishnavataram",
    "year": 2026,
    "slug": "Krishnavataram-(2026-India)",
    "url": "https://www.the-numbers.com/movie/Krishnavataram-(2026-India)",
    "leadCast": null,
    "director": "Hardik Gajjar",
    "thumbnail": null,
    "type": "movie"
  }
]
```

#### 5. Get movie details

Returns everything the movie page holds: box office, disc sales, metrics, details, daily/weekend/weekly performance and per-territory results.

**Method:** `GET`

**Endpoint:** `/v1/movie/details`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `slug` | query | Movie slug (e.g., "Interstellar-(2014)"). | string | Yes | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/proapi/the-numbers/v1/movie/details?slug=Avatar-Aang-The-Last-Airbender-%282026%29" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "slug": "Avatar-Aang-The-Last-Airbender-(2026)",
  "url": "https://www.the-numbers.com/movie/Avatar-Aang-The-Last-Airbender-(2026)",
  "title": "Avatar Aang: The Last Airbender (2026)",
  "poster": "https://media.the-numbers.com/images/movie-posters/Avatar-Aang-The-Last-Airbender-(2026).jpg",
  "opusDataId": 795150100,
  "synopsis": null,
  "boxOffice": {
    "domestic": null,
    "international": null,
    "worldwide": null
  },
  "discSales": {
    "dvd": null,
    "bluRay": null,
    "total": null
  },
  "metrics": [
    {
      "label": "Production Budget",
      "value": "$80,000,000"
    }
  ],
  "details": [
    {
      "label": "Domestic Releases",
      "values": [
        "July 24th, 2026 (Oscar Qualifying Run) by Paramount Pictures"
      ]
    },
    {
      "label": "Video Release",
      "values": [
        "Fall 2026 by Paramount +"
      ]
    }
  ],
  "weekendPerformance": [],
  "dailyPerformance": [],
  "weeklyPerformance": [],
  "territories": [],
  "territorySummary": []
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the data is in the response body. |
| 400 | Bad Request | A required parameter is missing or invalid, or the `x-api-market-key` header is missing. The body explains which. |
| 401 | Unauthorized | The `x-api-market-key` value is invalid or expired. |
| 403 | Forbidden | Your API.market subscription does not include this endpoint. |
| 404 | Not Found | The requested item does not exist (`{"error":true,"message":"Not found"}`), or there is nothing to return right now. Not billed. |
| 429 | Too Many Requests | You went over 10 requests/second (free trial) or 300 requests/second (PAYG), or used all 100 trial calls. |
| 500 | Internal Server Error | Something failed while fetching the data. Retry after a short delay. |
| 503 | Service Unavailable | The data source is temporarily unavailable. Retry later. |

## Rate Limits

The free trial allows 10 requests per second and 100 API calls over 7 days. The PAYG plan allows up to 300 requests per second with no monthly quota. Requests above the limit return `429 Too Many Requests`; throttle your client, back off before retrying, and honour any `Retry-After` header.

## FAQ

**Is this the official The Numbers API?**

No. This is an independent API that returns publicly visible data from The Numbers (the-numbers.com). It is not an official product of The Numbers and is not affiliated with or endorsed by it.

**Is there a free The Numbers API?**

Yes, the Free plan is a 7-day trial with 100 API calls at up to 10 requests per second, enough to test every endpoint.

**How much does The Numbers API cost?**

The pay-as-you-go plan has no monthly fee and costs US$0.001 per successful call, paid from your API.market wallet. Only successful (2xx) responses are billed.

**How do I find a movie's slug for the details endpoint?**

Call /v1/movie/search with at least 3 characters of the title, or take the slug from any row of /v1/box-office/daily-chart or /v1/box-office/weekend-chart. Slugs look like Interstellar-(2014).

**What happens if a movie is not found?**

The API returns 404 with {"error":true,"message":"Not found"} and the call is not billed. Invalid parameters return 400.

**Why does the weekend chart return 400?**

The date must be the Friday the weekend starts on, in Y-m-d format such as 2026-07-10. Any other weekday returns 400 with a message.

**Can I get inflation-adjusted grosses?**

Yes. Set inflation_adjusted=true on /v1/market/top-grossing-movies to get that year's top earners in inflation-adjusted dollars, or false for actual dollars.

**Do I need an API key from The Numbers?**

No. You only need your API.market key, sent in the x-api-market-key header to https://prod.api.market/api/v1/proapi/the-numbers.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


The Numbers API returns daily and weekend box office charts, movie grosses, budgets and disc sales as JSON. Start with a free trial.

The Numbers API: Daily & Weekend Box Office Data