CalTopo User Guide

https://training.caltopo.com/all_users/
Admin
CalTopo is a powerful mapping platform providing comprehensive training documentation covering all...
Tokens:135,320
Snippets:1,119
Trust Score:9.7
Update:1 day ago
Show doc for...
Tokens:
Raw
### CalTopo Team API Java Request Example

Source: https://training.caltopo.com/all_users/team-accounts/teamapi

Complete Java class demonstrating how to sign and send authenticated requests to the CalTopo Team API. Includes global credential constants, a signing method using HMAC-SHA256, parameter encoding, and a request method that handles both GET and POST with error handling.

```java
import org.json.JSONObject;

import java.io.BufferedReader;
import java.io.DataOutputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Main {

// Global variables.
public static final String CREDENTIAL_ID = "your credential ID";
public static final String CREDENTIAL_SECRET = "your credential secret";
public static final int DEFAULT_TIMEOUT_MS = 2 * 60 * 1000;

public static String sign(
        String method,
        String url,
        long expires,
        String payload,
        String credentialSecret
) {
    try {
        // Construct the message
        String message = method + " " + url + "\n"
                + expires + "\n"
                + (payload != null ? payload : "");

        // Decode the authentication key (Base64)
        byte[] secretKey = Base64.getDecoder().decode(credentialSecret);

        // Create a Mac instance with the HMAC-SHA256 algorithm
        Mac hmac = Mac.getInstance("HmacSHA256");
        SecretKeySpec keySpec = new SecretKeySpec(secretKey, "HmacSHA256");
        hmac.init(keySpec);

        // Generate the signature
        byte[] signatureBytes = hmac.doFinal(message.getBytes(StandardCharsets.UTF_8));

        // Return the signature as a Base64-encoded string
        return Base64.getEncoder().encodeToString(signatureBytes);

    } catch (Exception e) {
        throw new RuntimeException("Error while generating HMAC signature", e);
    }
}

public static String encodeParams(Map params) {
    String paramString = "";
    for (Map.Entry entry : params.entrySet()) {
        paramString += entry.getKey() + "=" + URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8) + "&";
    }
    return paramString.substring(0, paramString.length() - 1);
}

public static JSONObject caltopoRequest(
        String method,
        String url,
        String payload,
        String credentialId,
        String credentialSecret
) {
    try {
        method = method.toUpperCase();
        long expires = System.currentTimeMillis() + DEFAULT_TIMEOUT_MS;

        // Generate the signature
        String signature = sign(method, url, expires, payload, credentialSecret);

        // Construct the query string
        String query = "";
        Map params = new HashMap<>();
        params.put("id", credentialId);
        params.put("expires", String.valueOf(expires));
        params.put("signature", signature);
        if (method.equals("POST") && payload != null) {
            params.put("json", payload);
        } else {
            query = "?" + encodeParams(params);
        }

        // Construct the full URL
        String fullUrl = "https://caltopo.com" + url + query;

        // Open a connection
        HttpURLConnection connection = (HttpURLConnection) new URL(fullUrl).openConnection();
        connection.setRequestMethod(method);

        if (method.equals("POST") && payload != null) {
            connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
            connection.setDoOutput(true);
            OutputStream os = connection.getOutputStream();
            DataOutputStream dos = new DataOutputStream(os);
            dos.writeBytes(encodeParams(params));
            dos.flush();
            dos.close();
            os.close();
        }

        // Get the response code
        int responseCode = connection.getResponseCode();
        BufferedReader reader;

        // Handle the response stream
        if (responseCode == HttpURLConnection.HTTP_OK) {
            reader = new BufferedReader(new InputStreamReader(connection.getInputStream(),
                    StandardCharsets.UTF_8));
        } else {
            reader = new BufferedReader(new InputStreamReader(connection.getErrorStream(),
                    StandardCharsets.UTF_8));
        }

        // Read the response
        StringBuilder response = new StringBuilder();
        String line;
        while ((line = reader.readLine()) != null) {
            response.append(line);
        }
        reader.close();

        // Return the response if HTTP_OK, otherwise throw an error
        if (responseCode == HttpURLConnection.HTTP_OK) {
            JSONObject responseJson = new JSONObject(response.toString());
            return responseJson.getJSONObject("result");
        } else {
            throw new RuntimeException("Request failed with code " + responseCode
                    + ": " + response);
        }

    } catch (Exception e) {
        throw new RuntimeException("Error during CalTopo request", e);
    }
}
}
```

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

### Python example using caltopo_request to get account data

Source: https://training.caltopo.com/all_users/team-accounts/teamapi

Use this snippet to retrieve account objects created or changed since a given timestamp. The Service Account must have at least ADMIN permission. Replace 'your team ID' with the actual team ID and optionally set ts to a Unix timestamp in milliseconds; use 0 for all current data.

```python
team_id = "your team ID"

ts = 0  # Replace with a Unix timestamp in milliseconds if needed
team_data = caltopo_request(
    "GET",
    f"/api/v1/acct/{team_id}/since/{ts}",
    CREDENTIAL_ID,
    CREDENTIAL_SECRET,
)
```

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

### Example terminal output from debug logging

Source: https://training.caltopo.com/all_users/desktop/desktopaprs

Example of the data displayed in the CalTopo terminal window after adding the debug logging. It shows serial data, location reports, and local location reports with callsign and coordinates.

```text
2024-03-12 13:34:55 APRSLocalEngine [INFO] Serial data: N1WBU-7>APDR16:=4311.78N/07221.230W[157/000/A=000459 hi. 2024-03-12 13:34:55 SimpleLocationDispatcher [DEBUG] Location report LOCAL:N1WBU-7 @ 44.09633,-71.15383 2024-03-12 13:34:55 LocalLocationsService [DEBUG] Local location report LOCAL:N1WBU-7 @ 43.19633,-72.35383 2024-03-12 13:34:55 ForwardLocationsService [DEBUG] LOCAL:N1WBU-7 @ 43.19633,-72.35383
```

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

### topo.properties configuration for Mac with KISS mode

Source: https://training.caltopo.com/all_users/desktop/desktopaprs

Example configuration for a Mac, including the KISS sentence. Replace cu.usbmodem12345678 with your actual device name.

```properties
sarsoft.location.aprs.local.enabled=true
 sarsoft.location.cu.usbmodem12345678=1200,8,1,0
 sarsoft.location.serial.cu.usbmodem12345678.kiss=true
```
Tokens:
Raw