IPGeolocation MCP Server

Astronomy Time Series

get_astronomy_time_series

Read-only

Read-only daily astronomy series via GET /v3/astronomy/timeSeries. Works on free and paid plans. Cost: 1 credit per request. This endpoint covers date ranges up to 90 days; get_astronomy provides one-date and real-time sun/moon data.

Instructions

Returns { location, astronomy: [...] } with one daily item per date containing sunrise/sunset, moonrise/moonset, twilight blocks, day_length, sun/moon status, and moon_phase. Selector priority is lat/long, location, ip, then the server's public egress IP when no selector is provided.

dateStart and dateEnd are required YYYY-MM-DD values with a maximum 90-day span. lat and long must be provided together; elevation must be 0-10000 meters. time_zone changes timestamp formatting to include full dates. lang only changes location fields; non-English lang is paid-only and returns 401 on free plans. force_refresh bypasses cached data, makes a new upstream request, and can consume credits.

Input Schema

Name	Required	Description
`ip`	No	IPv4 or IPv6 address to get astronomy data for that IP's location.
`lat`	No	Latitude coordinate. Highest priority. Must be used with long.
`lang`	No	Response language for location fields in IP-based lookups (en, de, ru, ja, fr, cn, es, cs, it, ko, fa, pt, ar). Paid plans only. Free plan returns 401 for non-English languages.
`long`	No	Longitude coordinate. Must be used with lat.
`dateEnd`	Yes	End date in YYYY-MM-DD format. Required. Maximum range between dateStart and dateEnd is 90 days.
`location`	No	City or address string (e.g. San Francisco, CA).
`dateStart`	Yes	Start date in YYYY-MM-DD format. Required. Maximum range between dateStart and dateEnd is 90 days.
`elevation`	No	Elevation in meters above sea level (0-10000). Affects sunrise/sunset calculations.
`time_zone`	No	IANA timezone name to express times in (e.g. America/New_York). If set, time fields include full date instead of just time.
`force_refresh`	No	Default false. When true, bypasses cached astronomy time-series data; a successful refresh makes a new upstream request and can consume credits.

Output Schema

Name	Required	Description
`data`	No	Present on success: API result after field selection, redaction, and transport limits.
`page`	No
`error`	No	Present on failure, with isError: true.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv2.0.3Oct 28, 2026

removedOutput schema / properties / data / additionalProperties / anyOf

Removed value: -[
-  {
-    "type": "null"
-  },
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "array"
-  },
-  {
-    "type": "object"
-  }
-]

addedOutput schema / properties / data / additionalProperties / type

Added value: +[
+  "null",
+  "boolean",
+  "number",
+  "string",
+  "array",
+  "object"
+]

Addedv2.0.1Oct 13, 2026
Removedv2.0.0Jul 25, 2026

Changed1 schema field changedv1.0.15May 8, 2026

changedInput schema / properties / force_refresh / description

Previous value: -"Default false. Leave unset unless the user asks to refresh or rerun."New value: +"Default false. Set true only when the user asks to refresh cached astronomy time-series data; a successful refresh makes a new upstream request and can consume credits."

First observedv1.0.10Mar 16, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only cover readOnly/openWorld, but the description adds the operationally important traits: credit consumption, free-vs-paid gating with a specific 401 failure mode for non-English lang, force_refresh bypassing cache with new upstream request and possible credit spend, and the fallback to the server's egress IP when no selector is supplied. These are exactly the behaviors an agent cannot infer elsewhere.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose, endpoint, cost, and the sibling contrast, which is the right ordering. It loses a little to redundancy: the 90-day span cap is stated twice (once as scope, once per dateStart/dateEnd), and some parameter prose restates the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter, quota-metered, plan-gated endpoint, the description covers selection, cost, plan limits, caching, and selector resolution. An output schema exists and the description still summarizes the return shape, so nothing needed for a correct call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds value beyond it: the selector priority order (lat/long > location > ip > egress IP), the lat/long pairing rule, the 0-10000 elevation bound, and the note that lang only affects location fields. These are decision-relevant when an agent passes multiple selectors at once.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Read-only daily astronomy series") and even names the underlying endpoint, and it explicitly separates itself from the sibling get_astronomy ("provides one-date and real-time sun/moon data"). An agent can pick between the two without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly gives the selection condition (multi-day ranges up to 90 days) and points to the alternative for single-date and real-time use. It also states cost (1 credit/request) and plan eligibility up front, so the agent knows when the call is appropriate and what it costs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server