GMA API Documentation

Version 2.0 July 2026

1. Introduction
2. API Overview
3. Getting an API Key
4. Authentication
5. Read APIs
6. Spot Submit API
7. Request Examples
8. Response Examples
9. Error Handling
10. Rate Limits
11. Best Practices
12. Migration from Version 1
13. FAQ
14. Changelog
15. Contact

---

1. Introduction

The GMA API allows external software to retrieve GMA/WWFF spot data and submit new GMA spots.

Beginning with Version 2, API key authentication replaces legacy USER/PASSWORD authentication.

Two API key types exist:

| Prefix | Purpose |
|--------|---------|
| GMA- | Read APIs |
| GMS- | Spot submission |

Each key type is restricted to its intended purpose.

---

2. API Overview

Read APIs

/api/spots/gma/
/api/spots/10/
/api/spots/25/
/api/spots/wwff/

Write API

POST /api/spot-submit/

JSON is UTF-8 encoded.

Time values use UTC.

---

3. Getting an API Key

API keys are issued by the GMA administrators.

Please include:

Software name
Author
Project description
Contact e-mail
Website (optional)

Example:

Software: SmartGMA

Author: John Doe

Purpose: GMA spotting software

Each application should use its own API key.

---

4. Authentication

Preferred:

X-API-Key header

Example

X-API-Key: GMA-xxxxxxxx

Alternative:

?key=GMA-xxxxxxxx

Spot submission also accepts API_KEY inside the JSON body.

---

5. Read APIs

Current Spots

GET /api/spots/gma/

Last 10 Spots

GET /api/spots/10/

Last 25 Spots

GET /api/spots/25/

WWFF Spots

GET /api/spots/wwff/

Example:

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

---

6. Spot Submit API

Endpoint

POST /api/spot-submit/

Authentication

Valid GMS key required.

Required fields

MYCALL
ACTIVATOR
REF
KHZ
MODE

Optional

REMARKS

Example

{
  "SPOT":[
    {
      "MYCALL":"DL4MFM",
      "ACTIVATOR":"DL4MFM/P",
      "REF":"DA/NI-001",
      "KHZ":"7032.0",
      "MODE":"CW",
      "REMARKS":"CQ GMA"
    }
  ]
}

Dry run

Add

"DRY_RUN":1

to validate without inserting a spot.

---

7. Request Examples

Read:

curl -H "X-API-Key: GMA-xxxxxxxx" https://www.gma.rocks/api/spots/25/

Submit:

curl -X POST -H "Content-Type: application/json" -H "X-API-Key: GMS-xxxxxxxx"

---

8. Response Examples

Success

{
 "ok":true,
 "Inserted_Spots":"1"
}

Dry run

{
 "ok":true,
 "DRY_RUN":"ok",
 "Inserted_Spots":"0"
}

---

9. Error Handling

| HTTP | Meaning |
|------|---------|
|200|Success|
|400|Invalid request|
|401|Missing API key|
|403|Invalid or unauthorized key|
|405|Wrong HTTP method|
|429|Rate limit exceeded|
|500|Internal error|
|503|Service unavailable|

---

10. Rate Limits

Maximum one request per minute.

Maximum 1440 requests per UTC day.

Every request counts.

---

11. Best Practices

Cache responses for at least 60 seconds.
Respect the rate limits.
Send a meaningful User-Agent.
Always test using DRY_RUN before enabling live uploads.
Never publish API keys.
Handle HTTP errors gracefully.

---

12. Migration from Version 1

Legacy USER/PASSWORD authentication is deprecated.

All new software should use API keys.

---

13. FAQ

Can a GMA key submit spots?

No.

Can a GMS key read spot lists?

No.

Can API keys be revoked?

Yes.

---

14. Changelog

Version 2.0

API key authentication
Read/Write key separation
Spot Submit API
DRY_RUN support
Improved logging

---

15. Contact

Website

https://www.gma.rocks

Support

support@gma.rocks

---

Thank you for supporting the GMA community.