API Documentation

Programmatic access to your openFind.io tracking data.

Authentication

All API requests require a valid API key sent via the Authorization header using the Bearer scheme.

Generate an API key from Account Settings → API Keys.

Authorization: Bearer of_a1b2c3d4e5f6...

Keys have one of two scopes:

• read — can list devices, query history and sessions
• read,write — can also push location updates

Base URL

https://openfind.io/api/v1.php

All endpoints use query parameter action to select the operation.

Devices

GET ?action=devices

List all your devices.

curl -H "Authorization: Bearer of_YOUR_KEY" \
  "https://openfind.io/api/v1.php?action=devices"

GET ?action=device&id=N

Get details for a single device.

Parameter	Type	Description
id	integer	Device ID (required)

curl -H "Authorization: Bearer of_YOUR_KEY" \
  "https://openfind.io/api/v1.php?action=device&id=42"

Location Updates

POST ?action=location

Push a GPS location update for a device. Requires write scope.

Field	Type	Description
device_id	integer	Device ID (required)
lat	float	Latitude (required)
lng	float	Longitude (required)
accuracy	float	GPS accuracy in meters
altitude	float	Altitude in meters
speed	float	Speed in m/s
heading	float	Compass heading in degrees
location_name	string	Human-readable place name (auto-geocoded if omitted)

curl -X POST -H "Authorization: Bearer of_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device_id":42,"lat":37.7749,"lng":-122.4194}' \
  "https://openfind.io/api/v1.php?action=location"

Location History

GET ?action=location&device_id=N

Retrieve location history for a device (newest first).

Parameter	Type	Description
device_id	integer	Device ID (required)
limit	integer	Max records to return (1–500, default 100)

curl -H "Authorization: Bearer of_YOUR_KEY" \
  "https://openfind.io/api/v1.php?action=location&device_id=42&limit=50"

Sessions

GET ?action=sessions&device_id=N

List location sessions (trips) for a device. A session starts when tracking begins and ends when the user leaves or the browser closes.

Parameter	Type	Description
device_id	integer	Device ID (required)
limit	integer	Max sessions (1–50, default 20)

curl -H "Authorization: Bearer of_YOUR_KEY" \
  "https://openfind.io/api/v1.php?action=sessions&device_id=42"

Trail Points

GET ?action=trail&device_id=N&session_id=N

Get all GPS points for a specific session, ordered chronologically. Useful for drawing route paths.

Parameter	Type	Description
device_id	integer	Device ID (required)
session_id	integer	Session ID (required)

curl -H "Authorization: Bearer of_YOUR_KEY" \
  "https://openfind.io/api/v1.php?action=trail&device_id=42&session_id=7"

Errors

All errors return a JSON object with an error field:

{
  "error": "Device not found"
}

HTTP Code	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — missing, invalid, or revoked API key
403	Forbidden — insufficient scope (e.g., write needed)
404	Not found — device doesn't exist or isn't yours
405	Method not allowed

Rate Limits

The API currently does not enforce strict rate limits, but please be reasonable. Location updates more frequent than every 5 seconds will be throttled by the client. If you're building an integration, aim for one update per 10–30 seconds.

Examples

Python

import requests

API_KEY = "of_your_key_here"
BASE = "https://openfind.io/api/v1.php"
headers = {"Authorization": f"Bearer {API_KEY}"}

# List devices
devices = requests.get(f"{BASE}?action=devices", headers=headers).json()
for d in devices["devices"]:
    print(f"{d['name']}: {d['location_name']} ({'online' if d['is_online'] else 'offline'})")

# Push a location update
requests.post(
    f"{BASE}?action=location",
    headers={**headers, "Content-Type": "application/json"},
    json={"device_id": 42, "lat": 37.7749, "lng": -122.4194}
)

JavaScript (Node.js)

const API_KEY = "of_your_key_here";
const BASE = "https://openfind.io/api/v1.php";

// List devices
const res = await fetch(`${BASE}?action=devices`, {
  headers: { Authorization: `Bearer ${API_KEY}` }
});
const { devices } = await res.json();
devices.forEach(d => console.log(`${d.name}: ${d.location_name}`));

// Push a location
await fetch(`${BASE}?action=location`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ device_id: 42, lat: 37.7749, lng: -122.4194 })
});