Documentación de la API

Autenticación

Para utilizar la API, necesitas una clave. Puedes obtener tu clave de API en tu panel de usuario aquí. El plan gratuito incluye 5,000 solicitudes.

Envía tu clave en uno de los siguientes encabezados HTTP:

X-API-Key: TU_CLAVE_DE_API_AQUI

Authorization: Bearer TU_CLAVE_DE_API_AQUI

Adquisición de la Base de Datos

Cabeceras (Headers)

La API devuelve cabeceras útiles para entender el origen de los datos y gestionar tu cuota.

Cabeceras de Señal (Inteligencia)

• X-Geo-Source: Indica el origen del dato. local (nuestra base de datos) o mixed (enriquecido por Gaia ML).
• X-Geo-Filled: Muestra qué campos fueron rellenados por Gaia ML. Ej: city,province.
• X-Geo-Confidence: Nivel de confianza del resultado (de 0.00 a 1.00).

Cabeceras de Cuota

Usa estas cabeceras para controlar tu consumo en tiempo real.

• X-RateLimit-*: Límite de peticiones por minuto (Limit, Used, Remaining).
• X-Quota-Day-*: Cuota diaria (Limit, Used, Remaining).
• X-Quota-Month-*: Cuota mensual (Limit, Used, Remaining).
• X-Plan: Tu plan actual.

Endpoints

Comportamiento Inteligente

• Auto-completado: El sistema completa campos faltantes y persiste los resultados validados.
• Sugerencias: Con suggest=1, si hay múltiples coincidencias, la API devuelve un objeto suggestion para que el usuario elija.
• Relevancia: Los resultados se ordenan por coincidencia exacta, confianza, popularidad y presencia de coordenadas.

Buenas Prácticas

• Envía siempre el parámetro country en formato ISO-2.
• Para autocompletar, usa /search/city con limit bajo y suggest=1.
• Si recibes un error 429, implementa un backoff exponencial.
• Cachea las respuestas para mejorar la velocidad y no consumir tu cuota.
• Lee las cabeceras X-Geo-* y las de cuota para mejorar la experiencia de usuario.

Ejemplos de Cliente

cURL

BASE="https://geo.logihub.tech/api/geo"
API_KEY="tu_clave_de_api"
# Búsqueda de ciudad con sugerencias
curl -s "$BASE/search/city?country=IT&q=Roma&limit=5&suggest=1" \
  -H "X-API-Key: $API_KEY"

JavaScript (fetch)

const base = 'https://geo.logihub.tech/api/geo';
const key  = 'tu_clave_de_api';
const url = `${base}/search/postal?country=DO&q=10149&limit=5&suggest=1`;
const res = await fetch(url, { headers: { 'X-API-Key': key }});
const data = await res.json();
if (data.suggestion?.needs_selection) {
  // Muestra alternativas: data.suggestion.alternatives
  // GET /choose?selection_id=...&choice=0
}

PHP (Guzzle)

$client = new \GuzzleHttp\Client(['base_uri' => 'https://geo.logihub.tech/api/geo']);
$response = $client->get('/resolve/postal', [
  'query' => ['country' => 'IT', 'postal_code' => '38067', 'suggest' => '1'],
  'headers' => ['X-API-Key' => 'tu_clave_de_api']
]);
$body = json_decode($response->getBody()->getContents(), true);

Postman Collection

O descarga la colección completa de Postman desde este enlace.

SDK de PHP (Instalación y Uso)

GeoLogi, parte de logihub.tech, offre un SDK per facilitare l'integrazione nei tuoi progetti PHP.

Uso desde CLI

export GEOLOGI_API_KEY="LA_TUA_KEY"
# Esegui i comandi
php geologi-php-sdk/bin/geologi status
php geologi-php-sdk/bin/geologi search:city --country=IT --q=Roma --limit=5 --suggest=1
php geologi-php-sdk/bin/geologi resolve:postal --country=IT --postal=38067 --suggest=1

Uso en una aplicación PHP

require __DIR__ . '/geologi-php-sdk/autoload.php';
$client = new GeoLogi\Client('LA_TUA_KEY');
// Ricerca per città
$response = $client->searchCity('IT', 'Roma', 5, true);
var_dump($response->json(), $response->headers());
// Risoluzione per codice postale
$response = $client->resolvePostal('IT', '38067', true);
var_dump($response->json(), $response->headers());

SDK de Python (Instalación y Uso)

Instalación por SSH

# Descarga y descomprime
wget https://geo.logihub.tech/libreria/geologi-python-sdk-1.0.0.zip
unzip -o geologi-python-sdk-1.0.0.zip -d geologi-python-sdk-1.0.0

# Instala con pip
pip install ./geologi-python-sdk-1.0.0

Uso rápido

from geologi import Client

# El cliente puede leer la variable de entorno GEOLOGI_API_KEY
# o puedes pasarla directamente.
client = Client("TU_API_KEY")

r = client.search_city("IT", "Roma", limit=5, suggest=True)

print(r.json)
print(r.headers)

CLI incluido

export GEOLOGI_API_KEY="TU_API_KEY"

geologi status
geologi search:city --country IT --q Roma --limit 5 --suggest 1
geologi resolve:postal --country IT --postal 38067 --suggest 1

Métodos Disponibles

La clase Client proporciona los siguientes métodos:

• status()
• search_auto(country, q, limit=10, suggest=False)
• search_city(country, q, limit=10, suggest=False)
• search_postal(country, q, limit=10, suggest=False)
• resolve(country, postal_code=None, city=None, suggest=False)
• resolve_postal(country, postal_code, suggest=False)
• resolve_city(country, city, suggest=False)
• choose(selection_id, choice=None, postal_code=None, city=None)

SDK de Laravel (Instalación y Uso)

Instalación en un proyecto Laravel

# 1. Registrar el repositorio ZIP como un paquete de Composer
composer config repositories.geologi-sdk '{"type":"package","package":{"name":"geologi/laravel-sdk","version":"1.0.0","dist":{"url":"https://geo.logihub.tech/libreria/geologi-laravel-sdk-1.0.0.zip","type":"zip"},"autoload":{"psr-4":{"GeoLogi\\\\Laravel\\\\":"src/GeoLogi/Laravel/"}},"extra":{"laravel":{"providers":["GeoLogi\\\\Laravel\\\\GeoLogiServiceProvider"],"aliases":{"GeoLogi":"GeoLogi\\\\Laravel\\\\Facades\\\\GeoLogi"}}}}}'

# 2. Instalar el paquete
composer require geologi/laravel-sdk:1.0.0

# 3. Publicar el archivo de configuración
php artisan vendor:publish --provider="GeoLogi\Laravel\GeoLogiServiceProvider" --tag=config

Configuración .env

Añade las siguientes variables a tu archivo .env:

GEOLOGI_API_KEY=TU_KEY
GEOLOGI_BASE=https://geo.logihub.tech/api/geo
GEOLOGI_TIMEOUT=15

Uso en código

Puedes usar el Facade para realizar llamadas a la API de forma sencilla.

use GeoLogi\Laravel\Facades\GeoLogi;

$response = GeoLogi::searchCity('IT','Roma', 5, true);
$data = $response->json();

CLI Artisan

El SDK incluye varios comandos de Artisan para interactuar con la API desde la terminal.

# Comprobar el estado del servicio
php artisan geologi:status

# Buscar una ciudad
php artisan geologi:search-city IT Roma --limit=5 --suggest=1

# Buscar un código postal
php artisan geologi:search-postal DO 10149 --limit=5

# Resolver un código postal
php artisan geologi:resolve-postal IT 38067 --suggest=1

# Resolver una ciudad
php artisan geologi:resolve-city DO "Santo Domingo"

# Elegir una opción de una sugerencia
php artisan geologi:choose sel_123 --choice=0

Estructura del Paquete

La estructura de archivos del paquete Laravel es la siguiente:

geologi-laravel-sdk-1.0.0/
├── composer.json
├── LICENSE
├── README.md
├── config/geologi.php
└── src/GeoLogi/Laravel/
    ├── Client.php
    ├── GeoLogiServiceProvider.php
    ├── Response.php
    ├── Console/           # Comandos Artisan
    │   ├── ChooseCommand.php
    │   ├── ...
    ├── Exceptions/
    │   ├── HttpException.php
    │   └── RateLimitException.php
    └── Facades/
        └── GeoLogi.php