Bearer Token

Incluye el header Authorization en cada request:

Authorization: Bearer <tu_api_key>

Respuestas de error de autenticación

Dónde obtener tu API Key

Inicia sesión en la plataforma GPS → Menú de perfil → User Settings → campo API Hash. Ese valor es tu API Key.

{
  "object": "list",
  "count": 3,
  "data": [
    {
      "id": 200,
      "name": "Camion Ruta Norte",
      "status": "moving",
      "protocol": "teltonika",
      "lat": 4.710989,
      "lng": -74.072092,
      "speed": 68,
      "course": 45,
      "altitude": 2600,
      "last_seen": "2026-06-02 10:35:00",
      "driver": "Juan Perez",
      "address": "Autopista Norte Km 12, Bogota",
      "sensors": [
        { "type": "engine_hours", "name": "Horas motor", "value": "1240 h" },
        { "type": "battery", "name": "Bateria", "value": "13.2 V" }
      ],
      "group": "Flota Bogota"
    }
  ]
}

{ "error": "not_found", "message": "Dispositivo 999 no encontrado." }

Objeto Device

{
  "object": "location",
  "device_id": 200,
  "lat": 4.710989,
  "lng": -74.072092,
  "speed": 68,
  "course": 45,
  "altitude": 2600,
  "status": "moving",
  "address": "Autopista Norte Km 12, Bogota",
  "timestamp": 1748870100,
  "last_seen": "2026-06-02 10:35:00"
}

Objeto Location

Formato de error

{
  "error": "not_found",
  "message": "Dispositivo 999 no encontrado.",
  "docs": "https://developers.gpssoftwarenumberone.com"
}

Códigos HTTP

Rate Limits

La API acepta 100 requests por minuto por IP. Los headers de respuesta indican el estado del límite:

Python — Cliente completo

import requests
from typing import Optional

class GPSClient:
    BASE = "https://developers.gpssoftwarenumberone.com/api"

    def __init__(self, api_key: str):
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Accept": "application/json"
        })

    def get_devices(self) -> list:
        resp = self.session.get(f"{self.BASE}/v1/devices")
        resp.raise_for_status()
        return resp.json()["data"]

    def get_location(self, device_id: int) -> dict:
        resp = self.session.get(f"{self.BASE}/v1/devices/{device_id}/location")
        resp.raise_for_status()
        return resp.json()

    def get_events(self, device_id: Optional[int] = None, limit: int = 50) -> list:
        params = {"limit": limit}
        if device_id:
            params["device_id"] = device_id
        resp = self.session.get(f"{self.BASE}/v1/events", params=params)
        resp.raise_for_status()
        return resp.json()["data"]


# Uso
client = GPSClient("TU_API_KEY")

devices = client.get_devices()
for d in devices:
    loc = client.get_location(d["id"])
    print(f"{d['name']}: {loc['lat']}, {loc['lng']} — {loc['speed']} km/h")

JavaScript (Node.js) — Cliente completo

class GPSClient {
  constructor(apiKey) {
    this.baseUrl = "https://developers.gpssoftwarenumberone.com/api";
    this.headers = {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    };
  }

  async fetch(path, params = {}) {
    const url = new URL(this.baseUrl + path);
    Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
    const res = await fetch(url, { headers: this.headers });
    if (!res.ok) throw await res.json();
    return res.json();
  }

  getDevices()                    { return this.fetch("/v1/devices"); }
  getDevice(id)                   { return this.fetch(`/v1/devices/${id}`); }
  getLocation(id)                 { return this.fetch(`/v1/devices/${id}/location`); }
  getEvents(params = {})          { return this.fetch("/v1/events", params); }
  getGeofences()                  { return this.fetch("/v1/geofences"); }
}

// Uso
const client = new GPSClient("TU_API_KEY");
const { data: devices } = await client.getDevices();

for (const device of devices) {
  try {
    const loc = await client.getLocation(device.id);
    console.log(`${device.name}: ${loc.lat}, ${loc.lng}`);
  } catch (e) {
    if (e.error === "no_location") console.log(`${device.name}: sin posición`);
  }
}

v1.0.0 — Junio 2026

Lanzamiento inicial de la API pública GPS Tracking.

• Endpoint GET /v1/devices — lista de dispositivos
• Endpoint GET /v1/devices/:id — detalle de dispositivo
• Endpoint GET /v1/devices/:id/location — última posición
• Endpoint GET /v1/geofences — lista de geocercas
• Endpoint GET /v1/events — historial de eventos
• Autenticación Bearer token
• Rate limiting 100 req/min
• Sandbox interactivo

Selecciona un recurso en el menú lateral para ver su documentación detallada.

Generar una API Key

curl -X POST "https://developers.gpssoftwarenumberone.com/api/v1/keys" \
  -H "Content-Type: application/json" \
  -d '{"platform_hash":"TU_USER_API_HASH","label":"Mi integracion","expires_in_days":365}'

{
  "object": "api_key",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "gps_live_a1b2c3d4e5f6...",
  "label": "Mi integracion",
  "created_at": 1748822400000,
  "expires_at": 1780358400000,
  "platform_email": "usuario@empresa.com",
  "message": "Guarda esta clave — no se volvera a mostrar completa."
}

Listar tus API Keys

curl "https://developers.gpssoftwarenumberone.com/api/v1/keys" \
  -H "Authorization: Bearer TU_PLATFORM_HASH"

Revocar una API Key

curl -X DELETE "https://developers.gpssoftwarenumberone.com/api/v1/keys/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer TU_PLATFORM_HASH"

Formato de las keys

Todas las keys generadas tienen el prefijo gps_live_ seguido de 48 caracteres hexadecimales aleatorios:

gps_live_a1b2c3d4e5f6789012345678901234567890123456789012

Generar una key ahora

Descargar

Importar en Postman

1. Descarga el archivo gps-tracking-api-openapi.yaml
2. Abre Postman → Import → arrastra el archivo
3. Configura la variable api_key con tu user_api_hash
4. Usa demo_gps2024 para probar sin cuenta real

Importar en Swagger UI

Pega la URL de la especificacion en editor.swagger.io:

https://developers.gpssoftwarenumberone.com/openapi.yaml

Contenido de la coleccion

• GET /health — Estado del servicio (sin auth)
• GET /v1/devices — Listar todos los dispositivos
• GET /v1/devices/:id — Detalle de un dispositivo
• GET /v1/devices/:id/location — Ultima posicion GPS
• GET /v1/geofences — Listar geocercas
• GET /v1/events — Historial de eventos con filtros

Base URL

https://developers.gpssoftwarenumberone.com/api

Metodos HTTP

Formato de respuesta

Todas las respuestas son Content-Type: application/json. Las listas incluyen object, count y data. Los errores incluyen error (codigo), message (descripcion) y docs (enlace a documentacion).

{ "object": "list", "count": 3, "data": [...] }

{ "error": "not_found", "message": "Dispositivo 999 no encontrado.", "docs": "https://developers.gpssoftwarenumberone.com" }

Headers de respuesta

Cuando se supera el limite

El servidor responde con HTTP 429 Too Many Requests:

{ "error": "rate_limit_exceeded", "message": "Demasiadas solicitudes. Maximo 100 por minuto." }

Buenas practicas

• Implementa exponential backoff cuando recibas un 429.
• Usa caching local para datos que no cambian frecuentemente (geocercas, lista de dispositivos).
• Prefiere polling de posiciones a intervalos de 30+ segundos.