Overview

Astrospheric processes terrabytes of weather and astronomy data every month. The Data API (v2) lets Astrospheric Professional members access that data programmatically, alongside a new suite of astronomy calculation endpoints (rise/set, alt-az, moon, eclipses, time-zone, and IP-based location lookup) powered by the Astronomy Engine. The same surface is also available to AI agents via a remote MCP server!.

The Astrospheric Data API is available to Astrospheric Professional members for use in personal projects. Any API requests to endpoints not specified below are against Astrospheric's terms of use and may lead to IP blocks and/or charges.

We are currently working on an API for larger personal projects and commercial use. If you are interested in early access, please contact us at developer@astrospheric.com.

API Key

A private API key is required for every request. To get your key, visit the My Profile tab in Astrospheric and copy your key. The key is supplied in the JSON body of each request as the APIKey field. API access is a Pro feature, and all forecast variables and astronomy endpoints are available to any valid key.

Endpoint & Conventions

All APIs are hosted under the following base endpoint:

https://v2-api-public.astrospheric.com/api/

• Every endpoint is an HTTP POST request.
• The request body must be a JSON object.
• The response is JSON. Add "PrettyPrint": true to any request for indented output.
• All times are UTC, formatted as ISO 8601 (yyyy-MM-ddTHH:mm:ssZ).
• Latitude must be -90..90 and Longitude -180..180.
  • Weather forecast can only be created within the RDPS Domain (North America, Greenland, Iceland, Ireland, and the UK)

MCP Server (Preview)

The public API is also available as a remote Model Context Protocol (MCP) server, letting AI agents call Astrospheric tools directly. The tools reuse the same logic, authentication, and per-day credit billing as the HTTP endpoints above. Please note that tool calls to the MCP server generally use multiple API calls internally, so the credit cost of a tool call may be higher than the equivalent HTTP endpoint.

The MCP server is still in preview and feedback is welcome. At the moment it generally needs a model with a roughly 32k token context window to work well. We will continue to improve the server over time with the goal of allowing small local LLMs to use the tools effectively. Since tool discovery is dynamic you won't need to make changes while we improve the server.

• Tools call the underlying APIs which are billed at the same rate. Please note that most tool calls invoke multiple API calls.
• All times are UTC (ISO 8601); Latitude/Longitude follow the same ranges as the HTTP API.
• Errors are returned as a JSON object with an ErrorInfo field.

Connecting

The server is a remote HTTP MCP server. Point any MCP-capable client (GitHub Copilot CLI, Claude Desktop, LM Studio, Ollama etc.) at the server URL above. There are two ways to supply your API key — the custom header method is recommended.

{
  "mcpServers": {
    "Astrospheric MCP": {
      "url": "https://v2-api-public.astrospheric.com/runtime/webhooks/mcp",
      "headers": {
        "APIKey": "Your-API-Key"
      }
    }
  }
}

Option 2 — API key as a tool argument (fallback)

If your client cannot set custom headers, every tool also accepts an optional APIKey argument. The agent supplies it on each call. An explicit APIKey argument always takes precedence over the header. Your agent should ask for the api key if needed.

Credits & Billing

Each account has a monthly credit allowance of 29900 (the MonthlyAPICredit cap). Credits refresh at midnight UTC on the first day of each month. Every successful call consumes credits:

• GetForecastData — cost is the sum of the costs of every variable returned. A full-forecast request (no Variables array) is billed for all available variables.
• Astronomy endpoints — each call has a fixed per-endpoint cost.

Every response includes APICreditCostOfCall and APICreditsRemaining. If a call would exceed the monthly cap it is rejected with HTTP 403.

Rate Limiting

Requests are rate-limited per client IP address across all endpoints. Exceeding the rate limit returns HTTP 429 with a Too many requests message.

Error Handling

Errors return an appropriate HTTP status and a JSON envelope:

{ "ErrorInfo": "Latitude must be -90..90 and Longitude -180..180." }

GetForecastData

Returns the hourly forecast for a location using Astrospheric's data pipeline. You may request the full forecast or a subset of variables. The location must lie within the supported forecast domain or the API returns "No Data".

Request fields

Accepted variable names

Example request

{
  "APIKey": "YOUR_KEY",
  "Latitude": 47.6,
  "Longitude": -122.3,
  "Variables": ["Cloud", "Seeing", "Temperature"],
  "PrettyPrint": true
}

Example response (truncated)

{
  "TimeZone": "America/Los_Angeles",
  "UTCMinuteOffset": -480,
  "ModelTime": "2024_06_01_12",
  "HourForecastTime": "2024_06_01_13",
  "Latitude": 47.6,
  "Longitude": -122.3,
  "IsNBMAvailable": true,
  "APICreditCostOfCall": 3,
  "APICreditsRemainingToday": 9997,
  "Cloud": [
    {
      "Value": { "ValueColor": "#RRGGBB", "ActualValue": 12.0 },
      "HourOffset": 3,
      "UTCForecastHour": "2024-06-01T15:00:00Z"
    }
  ],
  "Seeing": [ ... ],
  "Temperature": [ ... ]
}

Variables not requested are returned as null. Each hourly entry contains a Value (ValueColor hex + numeric ActualValue), the HourOffset from the model run, and the UTCForecastHour.

RiseSet

Returns upcoming rise and set times for a named object or a custom RA/Dec target at a location.

Request fields

Accepted object names

Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto — or provide RA & Dec instead.

Example request

{
  "APIKey": "YOUR_KEY",
  "Latitude": 47.6,
  "Longitude": -122.3,
  "Object": "Sun",
  "Days": 3
}

Example response

{
  "Object": "Sun",
  "RA": null,
  "Dec": null,
  "Latitude": 47.6,
  "Longitude": -122.3,
  "RequestTimeUTC": "2024-06-01T00:00:00Z",
  "Days": 3,
  "Rises": [ "2024-06-01T12:11:00Z", ... ],
  "Sets":  [ "2024-06-02T04:03:00Z", ... ],
  "APICreditCostOfCall": 1,
  "APICreditsRemainingToday": 9999
}

AltAz

Returns the horizontal coordinates (azimuth/altitude) of an object at a given time and location.

Request fields

Example response

{
  "Object": "Jupiter",
  "RA": 4.213,
  "Dec": 21.55,
  "Latitude": 47.6,
  "Longitude": -122.3,
  "TimeUTC": "2024-06-01T08:00:00Z",
  "Azimuth": 102.4,
  "Altitude": 31.7,
  "IsAboveHorizon": true,
  "Direction": "Rising",
  "APICreditCostOfCall": 1,
  "APICreditsRemainingToday": 9999
}

Direction is "Rising" when the object's altitude is increasing at the requested time and "Setting" when it is decreasing.

Moon

Returns Moon illumination, position, distance, and the next four lunar phases.

Request fields

Example response

{
  "Latitude": 47.6,
  "Longitude": -122.3,
  "TimeUTC": "2024-06-01T08:00:00Z",
  "IlluminationPercent": 38.2,
  "PhaseAngle": 102.1,
  "Magnitude": -9.8,
  "DistanceKm": 389421.0,
  "Azimuth": 250.3,
  "Altitude": -12.4,
  "IsAboveHorizon": false,
  "NextPhases": [
    { "Phase": "Last Quarter", "TimeUTC": "2024-06-02T07:13:00Z" },
    { "Phase": "New Moon", "TimeUTC": "2024-06-06T12:38:00Z" }
  ],
  "APICreditCostOfCall": 1,
  "APICreditsRemainingToday": 9999
}

SolarEclipse

Returns the next solar eclipse. When Latitude/Longitude are supplied, it returns the next eclipse visible from that location with local circumstances and the maximum percent obscured. When lat/lon are omitted, it returns the next solar eclipse visible anywhere on Earth along with the location of greatest eclipse.

Request fields

Example response (with location)

{
  "Latitude": 44.0,
  "Longitude": -103.2,
  "SearchFromUTC": "2024-06-01T00:00:00Z",
  "Kind": "Total",
  "MaxObscurationPercent": 100.0,
  "TimeOfMaximumUTC": "2024-08-12T17:32:11Z",
  "MaximumAltitude": 48.2,
  "PartialBegin": { "TimeUTC": "2024-08-12T16:10:00Z", "Altitude": 41.0 },
  "TotalBegin":   { "TimeUTC": "2024-08-12T17:31:00Z", "Altitude": 48.1 },
  "Peak":         { "TimeUTC": "2024-08-12T17:32:11Z", "Altitude": 48.2 },
  "TotalEnd":     { "TimeUTC": "2024-08-12T17:33:20Z", "Altitude": 48.3 },
  "PartialEnd":   { "TimeUTC": "2024-08-12T18:55:00Z", "Altitude": 54.0 },
  "APICreditCostOfCall": 1,
  "APICreditsRemainingToday": 9999
}

TotalBegin and TotalEnd are null unless the eclipse is Total or Annular at the location.

Example response (no location — global)

{
  "SearchFromUTC": "2024-06-01T00:00:00Z",
  "Kind": "Total",
  "MaxObscurationPercent": 100.0,
  "TimeOfMaximumUTC": "2024-08-12T17:32:11Z",
  "PeakLatitude": 65.13,
  "PeakLongitude": -100.42,
  "APICreditCostOfCall": 1,
  "APICreditsRemainingToday": 9999
}

PeakLatitude / PeakLongitude give the location of greatest eclipse and are null for partial eclipses where no such point exists. Local contact times and altitudes are only returned when a location is supplied.

LunarEclipse

Returns the next lunar eclipse (a global event). When Latitude/Longitude are supplied, the API searches forward for the next eclipse visible from that location — the Moon is above the horizon during at least one phase — and includes a local visibility flag and the Moon's altitude at maximum. When lat/lon are omitted, it returns the next lunar eclipse globally without location-specific fields.

Request fields

Example response (with location)

{
  "Latitude": 47.6,
  "Longitude": -122.3,
  "SearchFromUTC": "2024-06-01T00:00:00Z",
  "Kind": "Total",
  "MaxObscurationPercent": 100.0,
  "TimeOfMaximumUTC": "2025-03-14T06:58:00Z",
  "MoonAltitudeAtMaximum": 33.5,
  "IsVisibleFromLocation": true,
  "PenumbralBeginUTC": "2025-03-14T03:57:00Z",
  "PenumbralEndUTC":   "2025-03-14T09:59:00Z",
  "PartialBeginUTC":   "2025-03-14T05:09:00Z",
  "PartialEndUTC":     "2025-03-14T08:47:00Z",
  "TotalBeginUTC":     "2025-03-14T06:26:00Z",
  "TotalEndUTC":       "2025-03-14T07:31:00Z",
  "APICreditCostOfCall": 1,
  "APICreditsRemainingToday": 9999
}

With a location, the API skips forward to the next eclipse where the Moon is above the horizon during any phase. Partial and Total boundary times are null for eclipse kinds that don't reach those phases (e.g. a penumbral eclipse).

Example response (no location — global)

{
  "SearchFromUTC": "2024-06-01T00:00:00Z",
  "Kind": "Total",
  "MaxObscurationPercent": 100.0,
  "TimeOfMaximumUTC": "2025-03-14T06:58:00Z",
  "PenumbralBeginUTC": "2025-03-14T03:57:00Z",
  "PenumbralEndUTC":   "2025-03-14T09:59:00Z",
  "PartialBeginUTC":   "2025-03-14T05:09:00Z",
  "PartialEndUTC":     "2025-03-14T08:47:00Z",
  "TotalBeginUTC":     "2025-03-14T06:26:00Z",
  "TotalEndUTC":       "2025-03-14T07:31:00Z",
  "APICreditCostOfCall": 1,
  "APICreditsRemainingToday": 9999
}

The global response omits MoonAltitudeAtMaximum and IsVisibleFromLocation.

Timezone

Resolves the IANA time-zone identifier and current UTC offset for a location.

Request fields

Example response

{
  "Latitude": 47.6,
  "Longitude": -122.3,
  "TimeZone": "America/Los_Angeles",
  "UTCOffsetSeconds": -25200,
  "UTCOffsetHours": -7.0,
  "APICreditCostOfCall": 1,
  "APICreditsRemainingToday": 9999
}

If the time zone cannot be resolved, Etc/UTC is returned.

IpLookup

Resolves an approximate location for the caller based on the IP of the request. Useful for seeding a default location when you don't yet have coordinates. Endpoint returns an error if location can't be determined

Request fields

Example response

{
  "Latitude": 47.606143,
  "Longitude": -122.332346,
  "IPAddress": "203.0.113.7",
  "APICreditCostOfCall": 1,
  "APICreditsRemainingToday": 9999
}

Try it (live examples)

Each example below is a complete, copy-pasteable fetch() snippet for one endpoint. Paste your API key into the box and press Run to call the live API straight from this page.

Heads up: these examples call the production API and consume real credits from your daily allowance, just like any other request. Example coordinates use a dark-sky site (39.03, -110.32).

const response = await fetch("https://v2-api-public.astrospheric.com/api/GetForecastData", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    APIKey: "YOUR_KEY",
    Latitude: 39.03,
    Longitude: -110.32,
    Variables: ["Cloud", "Seeing", "Temperature"]
  })
});
const data = await response.json();
console.log(data);

Response will appear here…

const response = await fetch("https://v2-api-public.astrospheric.com/api/RiseSet", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    APIKey: "YOUR_KEY",
    Latitude: 39.03,
    Longitude: -110.32,
    Object: "Sun",
    Days: 3
  })
});
const data = await response.json();
console.log(data);

Response will appear here…

const response = await fetch("https://v2-api-public.astrospheric.com/api/AltAz", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    APIKey: "YOUR_KEY",
    Latitude: 39.03,
    Longitude: -110.32,
    Object: "Jupiter"
  })
});
const data = await response.json();
console.log(data);

Response will appear here…

const response = await fetch("https://v2-api-public.astrospheric.com/api/Moon", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    APIKey: "YOUR_KEY",
    Latitude: 39.03,
    Longitude: -110.32
  })
});
const data = await response.json();
console.log(data);

Response will appear here…

const response = await fetch("https://v2-api-public.astrospheric.com/api/SolarEclipse", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    APIKey: "YOUR_KEY",
    Latitude: 39.03,
    Longitude: -110.32
  })
});
const data = await response.json();
console.log(data);

Response will appear here…

const response = await fetch("https://v2-api-public.astrospheric.com/api/LunarEclipse", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    APIKey: "YOUR_KEY",
    Latitude: 39.03,
    Longitude: -110.32
  })
});
const data = await response.json();
console.log(data);

Response will appear here…

const response = await fetch("https://v2-api-public.astrospheric.com/api/Timezone", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    APIKey: "YOUR_KEY",
    Latitude: 39.03,
    Longitude: -110.32
  })
});
const data = await response.json();
console.log(data);

Response will appear here…

const response = await fetch("https://v2-api-public.astrospheric.com/api/IpLookup", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    APIKey: "YOUR_KEY"
  })
});
const data = await response.json();
console.log(data);

Response will appear here…

The Astrospheric Data API is evolving. For feedback or commercial access, contact developer@astrospheric.com.