Name: Space & Science API - NASA Astronomy Picture of the Day
Brand: quotalink
SKU: api-quotalink-space-science-api
Availability: InStock
Author: API Market

李乐

## Overview

Space & Science API serves NASA's Astronomy Picture of the Day as clean JSON. Fetch today's image, any specific date since the archive began, or a whole date range in a single call.

Each entry carries the title, the full astronomer-written explanation, a standard and a high-resolution image URL, and a copyright credit where the image is not public domain. Responses are cached server-side, so repeated requests for the same date are fast and do not hit NASA again.

## Features

- **Today's picture**: one call, no parameters needed.
- **Any archive date**: the APOD archive runs from 16 June 1995 to today.
- **Date ranges**: pull a week or a month in one request for galleries and digests.
- **Standard and HD URLs**: `url` for display, `hdurl` for full resolution.
- **Video entries handled**: `media_type` tells you when an entry is a video rather than an image.
- **Copyright credit**: attribution where the image is not public domain.
- **Server-side caching**: repeat requests for the same date are served from cache.
- **No provider account needed**: your API.market key is the only credential.

## Use Cases

- **Daily space widgets**: an astronomy image of the day on a homepage or dashboard.
- **Wallpaper and screensaver apps**: pull HD imagery on a schedule.
- **Education and classroom tools**: illustrate lessons with NASA imagery and explanations.
- **Newsletters and digests**: fetch a week at a time and assemble a roundup.
- **Chat and social bots**: post the daily picture to a channel.
- **Galleries and archives**: browse historical entries by date range.

## API Documentation

### Base URL

```
https://prod.api.market/api/v1/quotalink/space-science-api
```

### Authentication

Pass your API.market key in the `x-api-market-key` header on every request. No other credential is needed.

```
x-api-market-key: YOUR_API_MARKET_KEY
```

Find your key under **Account → API Keys** on api.market. Requests without this header return `400` with `No x-api-market-key or x-magicapi-key defined in headers`.

### Dates

Dates use `YYYY-MM-DD`. The APOD archive starts on **1995-06-16**; anything earlier has no entry. Entries are published on US Eastern time, so "today" can lag your local date by a few hours.

### Endpoints

#### GET /apod

Returns one picture. Defaults to today.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `date` | query | string | No | `YYYY-MM-DD`, defaults to today |

```bash
curl "https://prod.api.market/api/v1/quotalink/space-science-api/apod" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "picture": {
    "date": "2026-08-25",
    "title": "Earth's Shadow Visualized with Lunar Eclipses",
    "explanation": "What's creating this giant hole in space? This is not a black hole ...",
    "url": "https://apod.nasa.gov/apod/image/2608/EarthShadow_Martin_960.jpg",
    "hdurl": "https://apod.nasa.gov/apod/image/2608/EarthShadow_Martin_4000.jpg",
    "media_type": "image",
    "copyright": "Tim Martin"
  }
}
```

A specific date works the same way:

```bash
curl "https://prod.api.market/api/v1/quotalink/space-science-api/apod?date=2026-07-04" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

`copyright` is null for public domain images, which is common for NASA-produced material. When `media_type` is `video`, `url` points at an embeddable video and `hdurl` may be absent, so branch on `media_type` before rendering an `<img>`.

#### GET /apod/range

Returns every picture between two dates, inclusive.

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `start_date` | query | string | Yes | `YYYY-MM-DD` |
| `end_date` | query | string | Yes | `YYYY-MM-DD` |

```bash
curl "https://prod.api.market/api/v1/quotalink/space-science-api/apod/range?start_date=2026-08-20&end_date=2026-08-22" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{
  "success": true,
  "count": 3,
  "pictures": [
    {
      "date": "2026-08-20",
      "title": "The Elephant's Trunk in Cepheus",
      "url": "https://apod.nasa.gov/apod/image/2608/IMG_5201.jpeg",
      "hdurl": "https://apod.nasa.gov/apod/image/2608/IMG_5201_full.jpeg",
      "media_type": "image"
    }
  ]
}
```

Range entries carry `date`, `title`, `url`, `hdurl` and `media_type` only. They do **not** include `explanation` or `copyright`, so call `/apod?date=` for the full text on an entry a user opens.

Omitting either date returns `400` with `{"error":"start_date and end_date required","success":false}`.

#### GET /health

Service liveness, including how many entries are currently cached.

```bash
curl "https://prod.api.market/api/v1/quotalink/space-science-api/health" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

```json
{ "service": "space-science-api", "status": "ok", "cache_size": 6 }
```

## Status Codes

| Code | Meaning | What to do |
| --- | --- | --- |
| `200` | Success | Parse the response body |
| `400` | Required parameter or the `x-api-market-key` header is missing | Send both range dates, and check headers |
| `401` | Invalid or expired API key | Verify the key under Account → API Keys |
| `403` | Your subscription does not cover this endpoint | Check your active plan |
| `429` | Plan quota exhausted or rate limit exceeded | Back off and retry, or upgrade |
| `502` | NASA returned no data for the request | Check the date is valid and on or after 1995-06-16 |
| `5xx` | Upstream error | Retry with exponential backoff |

## Rate Limits

Both plans allow up to **10 requests per second**. Quotas apply per billing period:

- **FREE**: 100 API units, hard limit. Requests are rejected once the quota is spent.
- **PRO**: 10,000 API units per month, hard limit.

Every endpoint costs one unit per request, and a range request costs one unit regardless of how many days it covers.

## Error Handling

Errors return JSON with an `error` field and `success: false`:

```json
{ "error": "start_date and end_date required", "success": false }
```

```json
{ "error": "NASA API returned empty data", "success": false }
```

A malformed date and a date before the archive begins both surface as a `502` with `NASA API returned empty data` rather than a `400`. Validate the format and the 1995-06-16 floor in your own code before calling, so you can show a useful message.

Retry `5xx` responses with exponential backoff.

## Implementation Guide

### Example Code

```python
from datetime import date, timedelta
import requests

BASE = "https://prod.api.market/api/v1/quotalink/space-science-api"
HEADERS = {"x-api-market-key": "YOUR_API_MARKET_KEY"}
ARCHIVE_START = date(1995, 6, 16)

def picture_for(day=None):
    params = {}
    if day:
        if day < ARCHIVE_START:
            raise ValueError("APOD archive starts 1995-06-16")
        params["date"] = day.isoformat()
    r = requests.get(f"{BASE}/apod", params=params, headers=HEADERS, timeout=20)
    r.raise_for_status()
    return r.json()["picture"]

def last_week():
    end = date.today()
    start = end - timedelta(days=6)
    r = requests.get(f"{BASE}/apod/range", headers=HEADERS, timeout=30,
                     params={"start_date": start.isoformat(),
                             "end_date": end.isoformat()})
    r.raise_for_status()
    return r.json()["pictures"]

pic = picture_for()
print(pic["title"])
print(pic["explanation"][:200])
```

```javascript
const BASE = "https://prod.api.market/api/v1/quotalink/space-science-api";
const headers = { "x-api-market-key": process.env.API_MARKET_KEY };

async function daily() {
  const res = await fetch(`${BASE}/apod`, { headers });
  if (!res.ok) throw new Error(`APOD failed: ${res.status}`);
  const { picture } = await res.json();
  return {
    title: picture.title,
    credit: picture.copyright ?? "Public domain",
    isVideo: picture.media_type === "video",
    display: picture.url,
    fullRes: picture.hdurl ?? picture.url,
    text: picture.explanation,
  };
}

const today = await daily();
console.log(today.title, today.isVideo ? "(video)" : "(image)");
```

### Performance Optimization

- Fetch the daily picture once per day and cache it. APOD updates once every 24 hours, so polling more often spends quota for identical data.
- Use `/apod/range` for galleries. One unit covers the whole window, where a loop over dates costs one unit per day.
- Cache historical entries indefinitely. A past date's picture never changes.
- Serve `url` in listings and load `hdurl` only when a user opens the full image, since HD files are large.
- Fetch the next day's entry a little after 00:00 US Eastern rather than at your own local midnight, which may be hours early.

## FAQ

**Do I need a NASA API key to use this?**

No. Your API.market key is the only credential required.

**How far back does the archive go?**

To 16 June 1995, the first Astronomy Picture of the Day.

**Why does a range result have no explanation text?**

Range entries return `date`, `title`, `url`, `hdurl` and `media_type` only. Call `/apod?date=` for the full explanation.

**Why is `copyright` sometimes null?**

The image is public domain, which is normal for NASA-produced material. Fall back to a generic credit when the field is empty.

**Some entries are videos. How do I detect that?**

Check `media_type`. When it is `video`, `url` is an embeddable video link rather than an image.

**Why did I get a 502?**

NASA returned no entry, which happens for a malformed date or one before 1995-06-16. Validate the date before calling.

**Does a range request cost more than one call?**

No. One request is one API unit no matter how many days it spans.

## 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.


Get NASA's daily astronomy pictures with explanations. Free API for space images, educational content, and science applications.