Name: Time Capsule API — "The Day You Were Born"
Brand: nicheapi-llc-1
SKU: api-nicheapi-llc-1-timecapsule
Availability: InStock
Author: API Market

True Scary Stories

# Time Capsule API

## Overview
The Time Capsule API delivers historical snapshots for any calendar date from 1950 through the present, combining pop culture, economic, and generational data into a single structured response. Submit a date and receive the Billboard Hot 100 number-one song, box office leader, consumer prices (gas, bread, median home, minimum wage), CPI-adjusted inflation figures, cultural headlines, technology milestones, the sitting president, and the generational context for anyone born on that day. A compare endpoint places two dates side by side for economic and cultural contrast, and a random endpoint supports discovery and engagement features. Data is sourced from Billboard, the US Census Bureau, the Bureau of Labor Statistics, Box Office Mojo, and the Library of Congress.

## Features

*   **Full Date Snapshots**: Every response covers music (Billboard Hot 100 #1), film (box office leader), consumer prices, inflation multipliers, cultural headlines, technology milestones, the sitting president, and generational classification — all for a single requested date.
*   **Coverage from 1950 to Present**: The dataset spans over 70 years of US historical data with consistent schema across the full range.
*   **Inflation Adjustment**: Every snapshot includes a CPI-derived multiplier showing what one dollar on that date is worth today, and what $100 then is worth now.
*   **Generational Context**: Returns a generation label (Boomer, Gen X, Millennial, Gen Z, Gen Alpha) and description for anyone born on the requested date.
*   **Two-Date Comparison**: Submit any two dates to receive both snapshots side by side for economic, cultural, and generational contrast.
*   **Today's Snapshot**: A dedicated endpoint returns the current date's snapshot without requiring a date parameter.
*   **Random Date Discovery**: A random endpoint returns a snapshot for a surprise date — suited for "On This Day" widgets, trivia, and nostalgia features.
*   **Test Sample Generation**: Generate multiple random snapshots in a single call for development, demos, and schema validation.
*   **Authoritative Data Sources**: Billboard, US Census Bureau, Bureau of Labor Statistics, Box Office Mojo, and Library of Congress — cited in every response via the `data_sources` field.

## Use Cases

The Time Capsule API is suited for a range of consumer, educational, and content workflows:

*   **Personal Nostalgia Apps**: Answer questions like "What was the #1 song on my birthday?" or "How much did gas cost the day I was born?" with a single API call per date.
*   **Content & Social Apps**: Power daily "On This Day" widgets, birthday cards with real historical data, and nostalgia-driven social sharing features using the snapshot or random endpoints.
*   **Education Platforms**: Show students how inflation, wages, consumer prices, and culture shifted across decades by comparing two dates or stepping through yearly snapshots.
*   **Financial Tools**: Use inflation-adjusted dollar comparisons and historic price anchoring to contextualize financial data — showing what a 1980 salary is worth today, for example.
*   **Gamification & Trivia**: Build "Guess the Year" features driven by real snapshot data — top song, gas price, and pop culture headline as clues.
*   **AI & LLM Agents**: Inject structured real-world historical context into agentic workflows that reason about specific dates, time periods, or generational cohorts.
*   **Entertainment & Marketing**: Drive nostalgia marketing campaigns with random discovery feeds or themed historical content tied to product anniversaries and brand milestones.


## API Documentation

### Base URL
All API requests for the Time Capsule API should be made to the following base URL:
`https://prod.api.market/api/v1/nicheapi-llc-1/timecapsule`

### Authentication
Authentication is handled via an API key obtained from RapidAPI. Include your key in the `x-api-market-key` header of every request:

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

Replace `YOUR_API_KEY` with your actual API key from RapidAPI. Note that the API overview endpoint (`GET /v1/timecapsule/`) does not require authentication.


### Endpoints

#### 1. Get Snapshot for a Specific Date

Retrieve the full historical snapshot for any calendar date between 1950 and the present.

**Method**: `GET`
**Endpoint**: `/v1/timecapsule/snapshot/{date}`

**Parameters**:

| Name | In | Description | Type | Required |
| :--- | :--- | :--- | :--- | :--- |
| `date` | path | Target date in ISO 8601 format (`YYYY-MM-DD`, e.g. `1994-03-17`) | `string` | Yes |

**Example Request**:

```bash
curl -X GET "https://prod.api.market/api/v1/nicheapi-llc-1/timecapsule/snapshot/1994-03-17" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK)**:

```json
{
  "date": "1994-03-17",
  "formatted_date": "Thursday, March 17, 1994",
  "top_song": {
    "title": "The Sign",
    "artist": "Ace of Base",
    "genre": "pop"
  },
  "prices": {
    "gallon_of_gas": "$1.10",
    "loaf_of_bread": "$0.78",
    "median_home": "$64,000",
    "median_income": "$26,000/yr",
    "minimum_wage": "$4.25/hr"
  },
  "inflation": {
    "dollar_then": 2.1,
    "one_dollar_then_is_now": "$0.48",
    "what_100_then_is_now": "$48"
  },
  "culture": {
    "top_movie": "Forrest Gump",
    "top_headline": "Nelson Mandela elected president",
    "technology": "Netscape Navigator, first internet bank",
    "president": "Bill Clinton"
  },
  "generation": {
    "label": "Millennial",
    "description": "Digital natives who came of age around 9/11..."
  },
  "special": {
    "major_events": [],
    "famous_birthdays": null
  },
  "data_sources": [
    "Billboard Hot 100",
    "US Census Bureau",
    "Bureau of Labor Statistics",
    "Box Office Mojo",
    "Library of Congress"
  ]
}
```

#### 2. Get Today's Snapshot

Returns the snapshot for the current date. No date parameter required.

**Method**: `GET`
**Endpoint**: `/v1/timecapsule/today`

**Example Request**:

```bash
curl -X GET "https://prod.api.market/api/v1/nicheapi-llc-1/timecapsule/today" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK)**: Same schema as the date snapshot endpoint.

#### 3. Get a Random Date Snapshot

Returns a snapshot for a randomly selected date. Suited for discovery feeds, "On This Day" widgets, and trivia features.

**Method**: `GET`
**Endpoint**: `/v1/timecapsule/random`

**Example Request**:

```bash
curl -X GET "https://prod.api.market/api/v1/nicheapi-llc-1/timecapsule/random" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK)**: Same schema as the date snapshot endpoint.

#### 4. Compare Two Dates

Compare the economic, cultural, and generational context of any two dates side by side. Returns both full snapshots under `date1` and `date2` keys in a single response.

**Method**: `POST`
**Endpoint**: `/v1/timecapsule/compare`

**Request Body**:

| Name | In | Description | Type | Required |
| :--- | :--- | :--- | :--- | :--- |
| `date1` | body | First date in ISO 8601 format (`YYYY-MM-DD`) | `string` | Yes |
| `date2` | body | Second date in ISO 8601 format (`YYYY-MM-DD`) | `string` | Yes |

**Example Request**:

```bash
curl -X POST "https://prod.api.market/api/v1/nicheapi-llc-1/timecapsule/compare" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "date1": "1994-03-17",
    "date2": "2020-03-11"
  }'
```

**Example Response (200 OK)**:

```json
{
  "date1": { "...full snapshot for 1994-03-17..." },
  "date2": { "...full snapshot for 2020-03-11..." }
}
```

#### 5. Run Test Scenarios

Generate a specified number of random date snapshots for testing, demos, and schema validation.

**Method**: `POST`
**Endpoint**: `/v1/timecapsule/test`

**Request Body**:

| Name | In | Description | Type | Required | Default |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `count` | body | Number of random snapshots to generate | `integer` | No | `1` |

**Example Request**:

```bash
curl -X POST "https://prod.api.market/api/v1/nicheapi-llc-1/timecapsule/test" \
  -H "x-api-market-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"count": 3}'
```

**Example Response (200 OK)**: Array of random snapshot objects, each following the date snapshot schema.

#### 6. API Overview

Returns the API welcome message and a map of available endpoints. Does not require authentication.

**Method**: `GET`
**Endpoint**: `/v1/timecapsule/`

**Example Request**:

```bash
curl -X GET "https://prod.api.market/api/v1/nicheapi-llc-1/timecapsule/"
```

**Example Response (200 OK)**:

```json
{
  "api": "Time Capsule API — The Day You Were Born",
  "version": "1.0.0",
  "endpoints": {
    "snapshot": "/v1/timecapsule/snapshot/{YYYY-MM-DD}",
    "today": "/v1/timecapsule/today",
    "random": "/v1/timecapsule/random",
    "compare": "POST /v1/timecapsule/compare",
    "test": "POST /v1/timecapsule/test"
  }
}
```


## Status Codes
Below is a list of common HTTP status codes you may encounter when interacting with the Time Capsule API:

*   **`200 OK`**: The request was successful and the server has returned the requested data.
*   **`400 Bad Request`**: The server could not process the request due to invalid input — most commonly a date string that does not conform to `YYYY-MM-DD` ISO 8601 format, a date outside the supported 1950–present range, or a missing required field in a POST body. Review your request before retrying.
*   **`401 Unauthorized`**: Authentication failed. Your `x-api-market-key` header is missing or contains an invalid key. Confirm your key is active and correctly included in the request header. Note that `GET /v1/timecapsule/` does not require authentication.
*   **`403 Forbidden`**: Your API key is valid, but the requested endpoint is not available on your current plan. The `/compare` and `/test` endpoints require Starter tier or above.
*   **`404 Not Found`**: No data was found for the requested date, or the endpoint path does not exist. Verify the date falls within the 1950–present coverage range and that the URL path matches the endpoint reference above.
*   **`429 Too Many Requests`**: You have exceeded your plan's rate limit. Implement client-side rate limiting and exponential backoff. Check the `Retry-After` response header for guidance on when to retry.
*   **`500 Internal Server Error`**: An unexpected server-side error occurred. Retry the request after a short delay.
*   **`503 Service Unavailable`**: The server is temporarily unavailable due to maintenance or elevated load. Retry after a short delay.

## Rate Limits

Rate limits vary by plan:

| Plan | Price | Requests | Rate Limit |
| :--- | :--- | :--- | :--- |
| **Free** | $0 | 100 req/day | — |
| **Starter** | $9.99/mo | 5,000 req/mo | 60 req/min |
| **Pro** | $29.99/mo | 25,000 req/mo | 300 req/min |
| **Enterprise** | Custom | Unlimited | Custom |

If you exceed your plan's rate limit, the API returns a `429 Too Many Requests` status code. Implement exponential backoff in your client and monitor the `Retry-After` header for retry timing guidance.

## FAQ

*   **What date range does the API cover?**
    The API covers 1950 through the present day. Submitting a date outside this range will return a `404` response. The `/today` endpoint always returns the current date's snapshot.

*   **What date format is required?**
    All dates must be provided in ISO 8601 format: `YYYY-MM-DD` (e.g., `1994-03-17`). Any other format will return a `400` error.

*   **What data is included in every snapshot?**
    Every snapshot includes the Billboard Hot 100 #1 song, box office leader, consumer prices (gas, bread, median home, median income, minimum wage), CPI-based inflation figures, a cultural headline, technology milestone, the sitting president, and a generational classification. The `data_sources` field in every response cites the authoritative origin for each data point.

*   **How is the inflation figure calculated?**
    The `inflation` object uses CPI data from the Bureau of Labor Statistics to compute the purchasing power multiplier between the requested date and today. `one_dollar_then_is_now` shows the present-day value of $1 on that date; `what_100_then_is_now` scales it to $100 for readability.

*   **Which endpoints require authentication?**
    All endpoints require an `x-api-market-key` header except `GET /v1/timecapsule/`, which returns the API overview and is publicly accessible without a key.

*   **Which endpoints are plan-restricted?**
    The Free plan includes the snapshot, today, and random endpoints. The `/compare` and `/test` endpoints require Starter tier or above.

*   **What does the compare endpoint return?**
    The `/compare` endpoint returns two full snapshot objects under `date1` and `date2` keys in a single response, using the same schema as the individual snapshot endpoint.

*   **How do I authenticate my requests?**
    All data endpoints require an `x-api-market-key` header with your API key obtained from RapidAPI.

*   **What is the rate limit for my plan?**
    Rate limits range from 60 req/min on Starter to 300 req/min on Pro, with custom limits for Enterprise. The Free plan is capped at 100 requests per day with no per-minute rate limit specified. See the Rate Limits section for the full breakdown.

## Contact Us

For questions or support, open a ticket via RapidAPI. Enterprise inquiries including dedicated support and custom data ranges can be directed through the same channel.

Relive any day in history. Get the top song, movie ticket prices, inflation-adjusted dollars, pop culture headlines, and generational context for any date.