API

The API offers the same functionality as the TLE search on the homepage.

Constructing a Query

The API works through GET requests, which means all the query parameters are passed through the URL. To make a request, you can either construct the URL manually or use CURL or the Python requests library to do it for you. We will give examples for all three.

The query parameters are identical to the ones on the TLE search form on the homepage and you can read more about how exactly they work there. Searching using the homepage will also return the URL for an equivalent (already validated) API request, so you can also use the homepage for constructing your queries.

The Satellite Data API returns a JSON object with three key/value pairs:

"results" contains a list of dictionaries, with each dictionary consisting of a TLE "id", "norad_str" and "satellite", with "norad_str" being the Two-Line Element in string format.
"next" is the URL for the next API request. "results" only contains 500 TLEs at a time, so for big requests, you will have to iterate through the "next" URLs until "next" is null.
"previous" is the URL for the previous API request, similarly to "next". Allows you to go back in the result pages.

Parameters

name	format	description
start-datetime	YYYYMMDDThhmm	Date and time. Required.
end-datetime	YYYYMMDDThhmm	Date and time. Required.
before	int	Nr of days. Optional. Set to 0 by default. If set to more than 0, returns an additional TLE outside the start and end range. For e.g. after, it will select the next entry after the end date, but won't search further than the nr of days given. This applies for every satellite retrieved by the search.
after	int
object-name	str	Optional. Case-insensitive, returns all that contain search term. Instead of whitespaces use "+".
norad-id	int	Optional. Must match exactly.
frequency-list	str of a list	Optional. List of Frequency Ranges, e.g. [10.0-12.2,13.5-14.0].
without-frequency-data	boolean	Required. True or False.

Example Request in the URL

The base URL for a TLE search API request is https://satdb.ethz.ch/api/satellitedata/. All search terms are then added after a question mark and concatenated with &, so we end up with a URL like this: base-url/?param1=value&param2=value

For our example request, we want to retrieve all TLE entries for the International Space Station on 09.04.2023. We also want one additional TLE before and after.

The ISS has the NORAD-ID 25544, which we specify as the parameter norad-id=25544. We set the start date to 09.04.2023 at midnight and the end date the next day also at midnight. This translates to the parameters start-datetime=20230409T0000 and end-datetime=20230410T0000. We include 3 days before (before=3) and after (after=3) in order to get the two additional TLEs. Lastly, we set without-frequency-data=True.

Adding all these parameters to the base URL, we get:


        https://satdb.ethz.ch/api/satellitedata/?norad-id=25544&start-datetime=20230409T0000&end-datetime=20230410T0000&before=3&after=3&without-frequency-data=True

To look at the results for this query, you can go here.

Example Request with Curl

You can use curl to make simple and easy API requests.

We can make a request from the command line with curl -G url -d parameter=value. This command takes the URL and appends the parameters (indicated by -d) before making a GET request. Following this syntax, our previous example request looks like this:


        $ curl -G https://satdb.ethz.ch/api/satellitedata/ \
            -d start-datetime=20230409T0000 \
            -d end-datetime=20230410T0000 \
            -d before=3 \
            -d after=3 \
            -d norad-id=25544 \
            -d without-frequency-data=True

If you are trying to fetch more than 500 TLEs, you will also have to request the following pages using the "next" URLs.

Example Request in Python

Here's an example on how to use the API in Python. The search parameters are the same as in the example above, and we are using the requests library to make our request. Additionally, we will loop over all (potential) pages and combine them into one string, 'tle_str', which has the same format as a TLE file.


        import requests

        url = 'https://satdb.ethz.ch/api/satellitedata'
        params = {
                'start-datetime': '20230409T0000',
                'end-datetime': '20230410T0000',
                'before': 3,
                'after': 3,
                'norad-id': 25544,
                'without-frequency-data': True,
		# 'frequency-list': '[10.7-12.7,13.85-14.5]',
		# 'object-name': 'ISS'
                }

        # initial request
        response = requests.get(url, params)
        next, results = response.json()['next'], response.json()['results']
        tle_str = '\n'.join(item['norad_str'] for item in results)

        # make next request
        while next != None:
            response = requests.get(next)
            results = response.json()['results']
            tle_str +=  '\n' +  '\n'.join(item['norad_str'] for item in results)
            next = response.json()['next']

Retrieving Satellites

While you can’t search satellites directly, if you want to know more about a satellite a TLE entry is associated with, you can query it using its database ID. Note that this is NOT the same as the NORAD ID.

You can find an associated satellite's ID when querying TLEs with '/api/satellitedata' under 'satellite'. To look up the satellite, simply append the ID to the url 'api/satellite/', so e.g. api/satellite/26173 for the ISS.