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.
| Route | Chunk | Chunks per request |
|---|---|---|
finance/events | year | 10 |
astronomy/phenomena | year | 5 |
astronomy/eclipse-local | year | 10 |
astronomy/seasons | year | 10 |
astronomy/rise-set | day | 31 |
astronomy/solunar | day | 31 |
finance/planetary-lines | series | 10 |
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.