// api
Overview
Access data on this site programmatically using custom, stable URLs with configurable parameters. The API conforms to the general principles of Representational State Transfer (REST) and returns data identical to the site's graphical interface.
If you are going to develop scripts that query our API and believe that developing or testing them could violate our API guidelines, please contact us to request access to our test server. This lets you develop your scripts against the same API without affecting the production environment.
// guidelines
API use guidelines
Throttling exists so operators relying on this data for spaceflight safety keep consistent performance.
API throttling
This platform is used primarily by satellite owners and operators for spaceflight safety, and throttles API use to maintain consistent performance for all users. To avoid error messages, limit your query frequency. Do not use multiple accounts simultaneously to circumvent these guidelines.
Limit API queries to fewer than 30 requests per 1 minute and 300 requests per 1 hour.
To prevent excess bandwidth costs, do not exceed the following data retrieval rates for your automated scripts, or your account may be suspended.
| Type | Frequency | Details |
|---|---|---|
| 60-DAY DECAY | 1 / week | Once per week, on Wednesdays after 1700 (UTC), for 60-day decay prediction data. |
| BOXSCORE | 1 / day | Once per day after 1700 (UTC) for Box Score data. |
| CDM | 3 / day | Once every 8 hours for all constellation Conjunction Data Messages (CDM). |
| CDM | 1 / hour | Once every hour for a specific conjunction event. Close-approach notifications still reach operators by email. |
| DECAY | 1 / day | Once you download an object's decay history, store it on your own servers; do not download it again. If checking daily, add "/MSG_EPOCH/%3Enow-1/" to retrieve current messages only. |
| Files panel | 1 / lifetime | Limit file downloads to no more than 50 files and 50MB per request. Once downloaded, store files on your own servers. |
| GP (aka TLEs) | 1 / hour | Once every hour for TLEs. Pick a random minute that is not at the top or bottom of the hour. Add "/decay_date/null-val/epoch/%3Enow-10/" so you only retrieve propagable ephemerides for on-orbit objects. |
| GP_HISTORY | 1 / lifetime | Do NOT use this class for current ephemerides — use GP. For many objects or large date ranges, download TLEs bundled as zip files by year from cloud storage instead. |
| Public files | 3 / day | Once every 8 hours. Moderate your activity; do not download more than 10 files per 15 minutes. |
| SATCAT | 1 / day | Once per day after 1700 (UTC) for SATCAT data. Follow best practices for downloading SATCAT daily. |
| SATCAT_DEBUT | 1 / day | Once per day after 1700 (UTC). If checking daily, add "/DEBUT/%3Enow-1/" to retrieve objects added to the catalog since yesterday. |
| TIP | 1 / hour | Add "/INSERT_EPOCH/%3Enow-0.042/" to limit the query to TIPs received since your last check. If an object is re-entering within 12 hours, you may query every 10 minutes using "/INSERT_EPOCH/%3Enow-0.005/" until the final TIP arrives. |
Retrieval strategy
Do not send hundreds of individual /class/gp/ or /class/satcat/ queries with one request per satellite. Use the API as efficiently as possible to minimize the number of requests, combining queries for multiple objects using a comma-delimited list where appropriate. See REST operators for more on comma-delimited lists.
With great power comes great responsibility
The query builder gives users a great amount of power and flexibility. Your account may be suspended if you violate the usage policy by querying data too often or by running queries that negatively impact the performance of the site. Repeat offenders may have their account suspended permanently. If your account has been suspended, you will receive instructions on what you need to do to have it reinstated.
We're here to help
We realize it can sometimes be challenging to craft an efficient query to retrieve the data you're looking for. Contact us at info@spacedatanetwork.xyz and tell us what you are trying to accomplish — we can help you customize your queries to meet your needs.