# NASA APOD MCP

> NASA APOD — Astronomy Picture of the Day accesses NASA's archive of daily space imagery, complete with expert explanations from professional astronomers. You can get today's image, pull a bulk set for any 30-day period in the last 30 years, or grab random finds to fill gaps in your content feed. Each entry includes images from Hubble and Webb, along with detailed scientific context.

## Overview
- **Category:** the-unthinkable
- **Price:** Free
- **Tags:** astronomy, space-exploration, image-archive, scientific-data

## Description

You need access to some seriously legit space data? This server pulls from NASA’s Astronomy Picture of the Day archive, giving you images and explanations from Hubble, Webb, and ground observatories alike. Every piece of content includes detailed scientific write-ups written by professional astronomers—it's not just a pretty picture for your feed. You use this to pull expert context alongside stunning imagery.

**`get_apod`**: Just need today’s deal? This tool pulls the official, current day's APOD entry. It gives you the title, the full explanation, and the media link for the single latest picture available. It’s straightforward; you get everything required to populate a daily content slot immediately.

**`get_apod_range`**: You gotta build out a historical feature or fill gaps in your archives? This tool lets you specify both a start date and an end date, retrieving up to thirty consecutive days of APOD data. It's perfect for bulk fetching metadata and images when you know exactly what time period you’re covering.

**`get_random_apod`**: Don't wanna stick to the calendar? This function pulls multiple random entries from the entire historical archive, spanning decades. You use this for novelty content or just filling out a section that needs unexpected space finds. It gives you variety without needing specific dates.

Every single call you make returns essential context data. The metadata includes copyright information and tells you whether the media asset it’s linking to is an image or a video, so your agent knows exactly what kind of file to expect. You get the full title, the comprehensive explanation from NASA experts, and the direct URL for the visual content itself.

When you pull data using `get_apod`, you're getting more than just a picture; you're pulling a complete package that includes the image link, the headline, and the detailed scientific write-up. Similarly, when you use `get_apod_range` with defined start and end parameters, you receive sequential metadata blocks for every day in that window, making batch processing simple.

The capability to pull random finds using `get_random_apod` means your content isn't predictable. You get a set of varied entries from the entire back catalog—it’s pure discovery material for your platform. The data you retrieve always includes the critical technical details: the copyright owner, whether it’s an image or video format, and all the necessary fields to build out a structured feed.

You don't just get pictures; you get professional context. That detailed explanation accompanying every APOD entry comes from working astronomers, giving your users real scientific depth alongside stunning visuals. You can pull today's image for instant updates, or set up a range query if you’re building an article about a specific historical astronomical event. The system handles the complexity of accessing decades of space data whether it's through `get_apod_range` or pulling random samples with `get_random_apod`. It provides consistency by always returning core fields like the title, media type indicator, and copyright status for every single entry you pull.

## Tools

### get_apod
Retrieves today's Astronomy Picture of the Day, including its title, explanation, and media link.

### get_apod_range
Fetches APOD data for a specified date range, limited to roughly 30 days per request.

### get_random_apod
Pulls multiple random APOD entries from the historical archive, useful for filler content.

## Prompt Examples

**Prompt:** 
```
What is today's astronomy picture?
```

**Response:** 
```
🌌 **Astronomy Picture of the Day**

**Title:** The Veil Nebula Supernova Remnant
**Date:** 2026-04-04
**Explanation:** The Veil Nebula is a large supernova remnant in the constellation Cygnus, the result of a star that exploded 8,000 years ago...

📸 Image: https://apod.nasa.gov/apod/image/2604/VeilNebula_Hubble.jpg
© NASA/HST
```

**Prompt:** 
```
Show me 3 random astronomy pictures
```

**Response:** 
```
🎲 **3 Random APODs**

1. 🪐 Saturn's Rings in Infrared (2019-09-15)
2. 🌌 Pillars of Creation — Webb (2022-10-19)
3. 🌍 Blue Marble 2012 (2012-01-25)

Each includes detailed astronomer explanations.
```

## Capabilities

### Retrieve Today's Image and Explanation
Your agent pulls the official, current day's APOD image URL, title, and the expert explanation.

### Bulk Fetch Historical Imagery
You specify a start date and end date to retrieve up to 30 consecutive days of images and metadata.

### Discover Random Space Finds
The agent fetches multiple random APOD entries from the entire historical archive for unexpected content.

### Get Core Metadata
Every API call returns essential context, including copyright and whether the media is an image or a video.

## Use Cases

### Creating a 'Month in Space' Feature
The goal is to show a full month of space discoveries. Instead of manually searching and compiling data, the agent simply executes `get_apod_range(start_date='2023-10-01', end_date='2023-10-31')`. This pulls all required images and explanations in one call, solving the content gap instantly.

### Handling Content Downtime
The daily scheduled job fails to pull `get_apod` due to a temporary API issue. Instead of showing an error message, the agent automatically falls back to calling `get_random_apod()`, ensuring the content section remains active and engaging for users.

### Building a Scientific Timeline
A developer needs images spanning two decades (e.g., 2005–2015). They use `get_apod_range` repeatedly across specific, non-contiguous blocks of dates to build a precise historical visual timeline.

### Populating an Archive Gallery
A user needs 10 random examples for a gallery mockup. The agent executes `get_random_apod()` with a count limit, giving the developer immediate access to diverse and verified space imagery without needing specific dates.

## Benefits

- Keeps your site fresh every day. By calling `get_apod`, you guarantee the most current, expert-vetted astronomical image and explanation without manual data entry.
- Builds rich historical content easily. Use `get_apod_range` to pull a full 30 days of images—perfect for month-in-review features or academic case studies.
- Provides reliable fallback content. If the current day's APOD is unavailable, `get_random_apod` instantly populates your feed with interesting historical finds.
- Saves time writing scientific copy. Every entry includes a detailed explanation written by a professional astronomer; you just need to format it and display it.
- Handles complex media types. The tool identifies if the content is an image or a video, ensuring your front-end renders the correct player.

## How It Works

The bottom line is that your AI client abstracts the API calls, allowing you to write code that pulls specific space data without worrying about NASA's endpoint details.

1. Your agent first determines the user's intent: Do they need today's data, a historical set, or just random filler?
2. The agent calls the appropriate function—`get_apod`, `get_apod_range(start_date, end_date)`, or `get_random_apod()`—passing necessary parameters like dates.
3. You receive structured data containing titles, image/video URLs, and the full text explanation for all requested entries.

## Frequently Asked Questions

**How do I get today's APOD using the `get_apod` tool?**
Just call `get_apod()`. This retrieves the full data set for the current day, including the title, image URL, and detailed explanation.

**`get_random_apod()` works like a backup? Is it safe to use?**
Yes, `get_random_apod()` is perfect for fallback content. It pulls genuinely random entries from the 30-year archive, giving you high-quality filler that looks authentic.

**Can I get data for a full year using `get_apod_range`?**
No. The tool has an effective limit of about 30 days per request. To cover a year, you'll need to wrap the call in a loop that iterates through sequential 30-day chunks.

**What fields does `get_apod` return besides the image?**
It returns several things: the title, the full explanation text written by an astronomer, the copyright holder, and the media type (image or video).

**What are the query rate limits when using `get_apod`?**
The service is designed for moderate, high-volume queries. However, always check the official NASA documentation for hard request ceilings. Exceeding these limits will result in a standard HTTP 429 error code.

**If I use `get_apod_range` with invalid dates, how does it handle errors?**
The tool returns an explicit error message detailing the failure. You must ensure your input parameters strictly follow the YYYY-MM-DD format for both start and end dates.

**How do I tell if `get_apod` is returning an image or a video?**
The returned data payload includes a 'media_type' field. This specific metadata tells your agent whether the provided URL links to a standard static image (JPEG/PNG) or a streamable video format.

**Do I need API keys when running `get_random_apod`?**
No, basic functionality for `get_random_apod` requires no personal credentials. The service uses standard public access endpoints, keeping the setup simple for your AI client.

**How far back does the APOD archive go?**
APOD has been publishing a new image or video every day since June 16, 1995 — over 10,000 entries spanning 30+ years of astronomical imagery.