Docs › CSV and bulk export

CSV and bulk export

Every tabular result as CSV, and long ranges as one gzip CSV whose every row carries the SHA-256 of the result it comes from.

?format=csv on a route

Add ?format=csv to a route's URL. Same price and quota as the JSON call; the response header X-Result-SHA256 is the hash of the JSON result the CSV is taken from. Nested fields become dotted columns (rise.local, best.altitude). Routes with a table: western/positions, western/aspects, western/sky, finance/events, finance/planetary-lines, finance/analogues, astronomy/rise-set, astronomy/altaz, astronomy/visibility, astronomy/moon, astronomy/seasons, astronomy/phenomena, astronomy/eclipse-local, astronomy/solunar.

POST /v1/export (Pro and Scale)

One request, a long range of one route, one CSV. The range is cut into the chunks the route answers in one call; each chunk counts as one call of your plan's quota (proportional quota), and each row has the chunk's result_sha256, the same hash the route returns for that chunk. One request computes at most the chunks below; when the range is longer, the X-Export-Next-Start header says where to continue (the Python SDK follows it for you). X-Export-Manifest-SHA256 hashes the ordered chunk hashes, to cite the whole file.

RouteChunkChunks per request
finance/eventsyear10
astronomy/phenomenayear5
astronomy/eclipse-localyear10
astronomy/seasonsyear10
astronomy/rise-setday31
astronomy/solunarday31
finance/planetary-linesseries10

Body: {"route", "start", "end", "params"}, where params are the route's own parameters without its date range (a place for rise-set and solunar, include for events, interval and bodies for the longitude series).

curl -s https://astro-agent.dev/v1/export \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" -H "Accept-Encoding: gzip" --compressed \
  -d '{"route": "finance/events", "start": "2000-01-01", "end": "2009-12-31", "params": {"include": ["eclipse"]}}' \
  -o eclipses_2000s.csv -D headers.txt

Python: CSV or Parquet

from astro_agents import Client

client = Client()                  # a Pro or Scale key in ASTRO_AGENTS_KEY
df = client.export("finance/events", "1800-01-08", "2199-12-30", include=["eclipse"])   # pages for you
df.to_csv("eclipses.csv.gz", index=False)          # or df.to_parquet("eclipses.parquet") (pyarrow)

Parquet is written on your side (pandas with pyarrow): the API sends CSV, gzip-compressed.

Errors

401 / 403 EXPORT_PLAN_REQUIRED without a Pro or Scale key; 400 for an invalid body or a chunk the route rejects (nothing counted); 429 when the units would pass your monthly quota. See errors.