# GMA Alert API Documentation

Version 1.0\
October 2026

## Table of Contents

1.  Introduction
2.  Endpoint
3.  Authentication
4.  Alert Selection
5.  Request Examples
6.  Response Format
7.  Field Description
8.  Error Handling
9.  Rate Limits
10. Best Practices
11. Contact

------------------------------------------------------------------------

# 1. Introduction

The GMA Alert API allows external software to retrieve current and
future public GMA alerts.

The API uses the same GMA read API keys as the GMA Spot APIs.

JSON is UTF-8 encoded.

All date and time values use UTC.

------------------------------------------------------------------------

# 2. Endpoint

GET /api/alerts/

Full URL:

https://www.gma.rocks/api/alerts/

------------------------------------------------------------------------

# 3. Authentication

A valid GMA read API key is required.

Preferred:

X-API-Key header

Example:

X-API-Key: GMA-xxxxxxxx

Alternative:

?key=GMA-xxxxxxxx

API keys with the GMS prefix are intended for spot submission and cannot
be used as read keys.

------------------------------------------------------------------------

# 4. Alert Selection

The API returns only public alerts whose scheduled date and time are
current or in the future.

The following alerts are not returned:

-   Past alerts
-   Hidden or non-public alerts
-   Deleted alerts
-   Internal alerts not intended for the public alert list

The response is sorted by date and time in ascending order.

------------------------------------------------------------------------

# 5. Request Examples

Preferred:

``` bash
curl -H "X-API-Key: GMA-xxxxxxxx" https://www.gma.rocks/api/alerts/
```

Alternative:

``` bash
curl "https://www.gma.rocks/api/alerts/?key=GMA-xxxxxxxx"
```

------------------------------------------------------------------------

# 6. Response Format

Example:

``` json
{
    "SOURCE": "Global Mountain Activity (GMA)",
    "RECORDS": "2 current/future alerts",
    "TIMESTAMP": 1790810298,
    "RCD": [
        {
            "ID": 278236,
            "DATE": "20261001",
            "TIME": "0800",
            "POSTER": "DL2DXA",
            "ACTIVATOR": "DL2DXA/P",
            "REF": "DA/SX-495",
            "QRG": "7031 10119 14061-CW",
            "TEXT": "DLFF-0056"
        },
        {
            "ID": 278276,
            "DATE": "20261001",
            "TIME": "1340",
            "POSTER": "DJ2MX",
            "ACTIVATOR": "DJ2MX/P",
            "REF": "DL/AM-134",
            "QRG": "HF-CW",
            "TEXT": "With Alex DL5AZZ"
        }
    ]
}
```

------------------------------------------------------------------------

# 7. Field Description

  Field       Description
  ----------- ---------------------------------------------------------
  SOURCE      Data source
  RECORDS     Number and type of returned records
  TIMESTAMP   Unix timestamp of the API response
  RCD         Array containing the alert records
  ID          Unique GMA alert ID
  DATE        Alert date in YYYYMMDD format, UTC
  TIME        Alert time in HHMM format, UTC
  POSTER      Callsign of the user who posted the alert
  ACTIVATOR   Callsign of the announced activator
  REF         GMA or supported programme reference
  QRG         Announced frequency/frequencies and/or mode information
  TEXT        Alert comment or additional information

------------------------------------------------------------------------

# 8. Error Handling

  HTTP   Meaning
  ------ -----------------------------
  200    Success
  401    Missing API key
  403    Invalid or inactive API key
  429    Rate limit exceeded
  500    Internal error

Example for a missing API key:

``` json
{
    "ok": false,
    "error": "missing_api_key",
    "message": "An API key is required for this API.",
    "source": "GMA Alert API",
    "website": "https://www.gma.rocks"
}
```

Example for rate limiting:

``` json
{
    "ok": false,
    "error": "rate limit exceeded",
    "message": "Please request gma.rocks alerts not more than once per minute."
}
```

A 429 response may include a Retry-After header indicating how many
seconds remain before another request is allowed.

------------------------------------------------------------------------

# 9. Rate Limits

Maximum one request per minute.

Maximum 1440 requests per UTC day.

Every request counts, including requests rejected because they were made
too frequently.

Rate limit information is also returned in HTTP headers:

-   X-RateLimit-Limit
-   X-RateLimit-Remaining
-   X-RateLimit-Reset
-   Retry-After (when applicable)

------------------------------------------------------------------------

# 10. Best Practices

-   Cache responses for at least 60 seconds.
-   Respect the rate limits.
-   Prefer the X-API-Key header instead of placing the API key in the
    URL.
-   Send a meaningful User-Agent.
-   Never publish API keys.
-   Handle HTTP errors gracefully.
-   Treat DATE and TIME as UTC.

------------------------------------------------------------------------

# 11. Contact

Website

https://www.gma.rocks

Support

support@gma.rocks

------------------------------------------------------------------------

© 2026 Global Mountain Activity

Thank you for supporting the GMA community.