AstroHub API

AstroHub API provides access to weather data collected at the Assy-Turgen observatory near Almaty, Kazakhstan, as well as to the astronomical seeing data.

The weather data is available since May, 2021, with the maximum resolution of 2 seconds.

API requests should be made over HTTPS to the following URL:

https://astrohub.fai.kz:8000

NOTE: API rate limit is enabled - maximum of 100 queries per minute.

API Key

To make use of the API, you need to have an API key. You can get one by sending a request to astrohub@fai.kz. Include the name of your organization.

The API key should be included in the X-API-Key header of the request.

Endpoints

`GET /weather/{parameter}` - weather data

Available parameters:

temp - ambient temperature (°C)
wind - wind speed (km/h); might contain negative values for diagnostic modes
sky - sky-ambient temperature, 999.9 saturated hot, -999.9 saturated cold, or -998.0 for wet
hum - relative humidity (%)
dew - dew point temperature (°C)
aday - daylight photodiode raw A/D output
hea - rain heater percentage
wndtd - anemometer tip temperature difference from ambient, limited by reducing anemometer heater power when 25C is reached
wdrop - maximum drop in wetness oscillator counts this cycle due to rain drops
wavg - wetness oscillator count difference from base dry value
wdry - wetness oscillator count difference for current dry from base dry value
rwosc - raw counts from the wetness oscillator

`GET /seeing` - astronomical seeing

Query data for the astronomical seeing at the observatory (not implemented yet).

Query Parameters

start beginning of the time range.
end - end of the time range.
resolution (optional) - resolution of the data (e.g., 1s, 1m, 1h, 1d). Default: 1h.
aggregation (optional) - aggregation function that defines what should be returned for each resolved interval. One of: mean, median, max, min. Default: mean.
limit (optional) - limit the number of returned data points per page. Default: 1000. Maximum is 10000.
offset (optional) - offset for the data points (see Pagination below). Default: 0.

Format for start and end parameters: ISO 8601 date format (YYYY-MM-DD) or ISO 8601 date-time format (YYYY-MM-DDTHH:MM:SSZ). Use UTC time zone.

Duration format for resolution parameter: <number><unit>, e.g.:

10s: 10 seconds
5m: 5 minutes
1h: 1 hour
2d: 2 days
3w: 3 weeks
6mo: 6 months
1y: 1 year

Pagination

Pagination is used to retrieve a large number of data points. The client should keep track of the number of data points returned and use the limit and offset parameters appropriately to retrieve the next set of data points.

For example, if you query data for three years with the resolution of 1h, you will expect 26,280 data points. In this case you can set the limit to 10000, and then expect 3 pages (with the last one having less than 10,000 points). Then, in first query the offset is 0, in the second query the offset should be set to 10000, and in the third query to 20000.

NOTE: Be prepared to receive less data points than requested, as not all data might be available for the requested time range (e.g., due to temporary issues with the weather station at certain periods). For that, check the number of data points in each response and decide if the next page query is needed.

Responses

In case of successful query, the returned status code is 200 and the response body contains data in JSON format:

{
    "parameter": "<name>",
    "data": [
        {
            "time": "<timestamp>",
            "value": <value>
        },
        ...
    ]
}

The timestamps are given in UTC (not local observatory’s time). The timezone of the Assy-Turgen observatory is UTC+5.

In case of an error (invalid API key, invalid parameter name, invalid query parameter, invalid value for query parameter), the response status code is 4xx or 5xx, and the response body contains an error message in JSON format.

Examples

Get wind speed data for Nov 09, 2024 (Assy-Turgen timezone), with 5 seconds resolution (and mean aggregation). Expecting 17,280 points, so setting limit to maximum (10000) and queering for 2 pages:

# Request 1 (note that 19:00 UTC is the beginning of the next date in Assy-Turgen timezone):
curl -H "X-API-Key: <your_key>" "https://astrohub.fai.kz:8000/weather/wind?start=2024-11-08T19:00:00Z&end=2024-11-09T19:00:00Z&resolution=5s&limit=10000"

# check that the number of returned data points is 10000. If so, proceed to the next page request using offset:
curl -H "X-API-Key: <your_key>" "https://astrohub.fai.kz:8000/weather/wind?start=2024-11-08T19:00:00Z&end=2024-11-09T19:00:00Z&resolution=5s&limit=10000&offset=10000"

Get temperature data for years 2021-2023, with 1 hour resolution, and with minimum value for each hour. Expecting 26,280 points, so setting limit to maximum (10000) and querying for 3 pages:

# Request 1:
curl -H "X-API-Key: <your_key>" "https://astrohub.fai.kz:8000/weather/temp?start=2021-01-01T00:00:00Z&end=2024-01-01T00:00:00Z&aggregation=min&resolution=1h&limit=10000"

# Request 2:
curl -H "X-API-Key: <your_key>" "https://astrohub.fai.kz:8000/weather/temp?start=2021-01-01T00:00:00Z&end=2024-01-01T00:00:00Z&aggregation=min&resolution=1h&limit=10000&offset=10000"

# Request 3:
curl -H "X-API-Key: <your_key>" "https://astrohub.fai.kz:8000/weather/temp?start=2021-01-01T00:00:00Z&end=2024-01-01T00:00:00Z&aggregation=min&resolution=1h&limit=10000&offset=20000"

Querying from the browser

To make queries directly from the browser, you can use the Swagger UI at the following URL: https://astrohub.fai.kz:8000/docs

After authorizing with your API key, expand the endpoint section and click “Try it out”.

This page also contains the auto-generated API documentation.

Bugs

If you encounter any issues, please send an email to astrohub@fai.kz.