Hermes GPS API - Documentación

Esta es la documentación de la API GPS de Hermes para consulta de ubicaciones de dispositivos GPS en tiempo real.

Autenticación

Todas las solicitudes a la API requieren una clave de API válida. La clave debe ser enviada en el header X-API-Key.

X-API-Key: tu-clave-api-aqui

Importante: Mantén tu clave de API segura y no la compartas públicamente. Las claves de API tienen acceso completo a los datos de ubicación de tus dispositivos.

Endpoints Disponibles

Obtener Ubicaciones de Dispositivos

GET /v1/get-locations

Obtiene las ubicaciones actuales de todos los dispositivos GPS asociados al cliente autenticado.

Headers Requeridos

Header	Tipo	Descripción
X-API-Key	string	Clave de API del cliente (requerido)

Parámetros

Este endpoint no requiere parámetros adicionales.

Respuesta Exitosa (200 OK)

{
  "fecha_de_actualizacion": "2025-08-29 15:30:45",
  "dispositivos": [
    {
      "id": "device123",
      "placa": "ABC-123",
      "name": "Vehiculo 1",
      "posicion": {
        "lat": -12.046374,
        "lng": -77.042793,
        "speed": 25,
        "fecha": "2025-08-29 15:30:45"
      }
    },
    {
      "id": "device456",
      "placa": "XYZ-789",
      "name": "Vehiculo 2",
      "posicion": {
        "lat": -12.050000,
        "lng": -77.045000,
        "speed": 0,
        "fecha": "2025-08-29 15:28:30"
      }
    }
  ]
}

Campos de Respuesta

Campo	Tipo	Descripción
fecha_de_actualizacion	string	Última fecha de sincronización de datos
dispositivos	array	Lista de dispositivos GPS
dispositivos[].id	string	ID único del dispositivo
dispositivos[].placa	string	Placa del vehículo
dispositivos[].name	string	Nombre descriptivo del dispositivo
dispositivos[].posicion	object	Información de ubicación
dispositivos[].posicion.lat	number	Latitud GPS
dispositivos[].posicion.lng	number	Longitud GPS
dispositivos[].posicion.speed	number	Velocidad en km/h
dispositivos[].posicion.fecha	string	Fecha y hora de la última ubicación

Verificar Salud del Sistema

GET /h

Verifica el estado de salud de la API. No requiere autenticación.

Respuesta

{
  "status": "ok",
  "timestamp": "2025-08-29T15:30:45Z"
}

Documentación

GET /docs

Muestra esta documentación en formato web. No requiere autenticación.

Códigos de Respuesta HTTP

Código	Descripción
200	Solicitud exitosa
401	No autorizado - No se proporcionó clave de API
403	Prohibido - Clave de API inválida o inactiva
429	Demasiadas solicitudes - Se ha excedido el límite de rate limiting
500	Error interno del servidor

Rate Limiting

La API implementa limitación de velocidad para proteger el servicio:

60 solicitudes por minuto por clave de API
1000 solicitudes por hora por clave de API

Cuando se exceden estos límites, recibirás un error HTTP 429.

Ejemplos de Uso

cURL

curl -X GET "https://hermesv2.geosatelital.com/v1/get-locations" -H "X-API-Key: tu-clave-api-aqui"
 
curl -X GET "https://hermesv2.geosatelital.com/h"

JavaScript (fetch)

// Obtener ubicaciones
const response = await fetch('/v1/get-locations', {
  method: 'GET',
  headers: {
    'X-API-Key': 'tu-clave-api-aqui'
  }
});

const data = await response.json();
console.log(data);

Python (requests)

import requests
 
headers = {'X-API-Key': 'tu-clave-api-aqui'}
response = requests.get('https://hermesv2.geosatelital.com/v1/get-locations', headers=headers)
data = response.json()

print(data)

Notas Técnicas

Formato de Fecha: Todas las fechas están en zona horaria de Lima (America/Lima)
Formato de Coordenadas: Las coordenadas GPS están en formato decimal
Actualización de Datos: Los datos se sincronizan automáticamente cada minuto
Codificación: Todas las respuestas están codificadas en UTF-8
Formato de Respuesta: JSON únicamente

Soporte

Para soporte técnico, preguntas sobre la API o reportar problemas:

Email: plataforma@geosatelital.com
Documentación: https://hermesv2.geosatelital.com/docs
Estado del Servicio: https://hermesv2.geosatelital.com/h

Última actualización: Agosto 2025

🔑 Probador de API

Ingresa tu clave de API para probar el endpoint y obtener la respuesta JSON: