Documentación de la API de Banderas

Autenticación

Incluye tu clave API en uno de los siguientes encabezados:

X-API-Key: TU_CLAVE_DE_API_AQUI

Authorization: Bearer TU_CLAVE_DE_API_AQUI

Para usar en etiquetas <img> en frontends sin un backend, puedes pasar la clave como un parámetro de query:

<img src="...?key=TU_CLAVE_DE_API_AQUI">

Límites y Cuotas

Cada respuesta autenticada incluye las siguientes cabeceras para el control de cuotas:

X-Plan
X-RateLimit-Limit
X-RateLimit-Used
X-RateLimit-Remaining
X-Project-ID (si aplica)

Errores comunes por límites:

429 rate_limit_minute
429 quota_daily
429 quota_month

Cache

Las respuestas de las banderas están optimizadas para el cacheado:

Cache-Control: public, max-age=604800, immutable (7 días)
ETag y soporte para If-None-Match, que puede resultar en una respuesta 304 Not Modified.

Endpoints

GET /status

Comprueba la salud del servicio.

Respuesta 200

{
  "ok": true,
  "service": "flags-api",
  "version": "v1",
  "time": "2025-09-16T00:00:00Z"
}

GET /flag

Obtiene la bandera de un país.

Parámetros de Query

country string, requerido. Acepta ISO-2 (IT), ISO-3 (ITA), o nombres/alias (Italia, República Dominicana, EEUU, etc.).
mode string, opcional. json | redirect | raw (default: json).
size string, opcional. small | normal | large (default: normal).

Respuesta 200 (mode=json)

{
  "ok": true,
  "data": {
    "iso2": "IT",
    "name": "Italy",
    "flag": {
      "size": "normal",
      "path": "/asset/flags/normal/it.png",
      "url": "https://geo.logihub.tech/asset/flags/normal/it.png",
      "mime": "image/png"
    }
  }
}

Otras respuestas: 302 Redirect (para mode=redirect) y 200 binario (para mode=raw).

GET /list

Devuelve un listado paginado de países y sus banderas.

Parámetros de Query

limit integer, opcional. (1–250, default: 250).
offset integer, opcional. (≥0, default: 0).
size string, opcional. small | normal | large (default: normal).

Respuesta 200

{
  "ok": true,
  "count": 2,
  "data": [
    {
      "iso2": "DO",
      "name": "Dominican Republic",
      "flag": { "size": "normal", "path": "/asset/flags/normal/do.png", ... }
    },
    {
      "iso2": "IT",
      "name": "Italy",
      "flag": { "size": "normal", "path": "/asset/flags/normal/it.png", ... }
    }
  ],
  "paging": { "limit": 250, "offset": 0 }
}

Integración Rápida

cURL

curl -H "X-API-Key: $KEY" "https://geo.logihub.tech/api/flags/flag?country=US&mode=json&size=large"

PHP

$key = 'TU_KEY';
$url = 'https://geo.logihub.tech/api/flags/flag?country=UK&mode=json';
$ctx = stream_context_create(['http'=>[
  'header'=>"X-API-Key: $key\r\nAccept: application/json\r\n"
]]);
$resp = json_decode(file_get_contents($url,false,$ctx), true);
echo $resp['data']['flag']['url'];

HTML (etiqueta <img>)

<img src="https://geo.logihub.tech/api/flags/flag?country=ITA&mode=redirect&size=small&key=TU_KEY" alt="IT">

Python

import urllib.request, json
KEY="TU_KEY"
req=urllib.request.Request(
  "https://geo.logihub.tech/api/flags/flag?country=DOM&mode=json&size=large",
  headers={"X-API-Key": KEY, "Accept": "application/json"}
)
with urllib.request.urlopen(req) as r:
    print(json.loads(r.read().decode())["data"]["flag"]["url"])

Node.js (con node-fetch)

import fetch from "node-fetch";
const KEY = process.env.GEO_KEY;
const r = await fetch("https://geo.logihub.tech/api/flags/flag?country=Spain&mode=json", {
  headers: {"X-API-Key": KEY, "Accept":"application/json"}
});
console.log((await r.json()).data.flag.url);

Buenas Prácticas

Usa mode=redirect para etiquetas <img> y reduce la lógica en el frontend.
Cachea las respuestas respetando ETag y Cache-Control.
Si persistes datos, normaliza el identificador del país a ISO-2.
Evita exponer tu clave en el lado del cliente. Prefiere un proxy en tu backend.

Esquemas de Datos

FlagItem

{
  "iso2": "IT",
  "name": "Italy",
  "flag": {
    "size": "normal",
    "path": "/asset/flags/normal/it.png",
    "url": "https://geo.logihub.tech/asset/flags/normal/it.png",
    "mime": "image/png"
  }
}

OpenAPI 3.0

Puedes importar esta especificación en herramientas como Postman para generar una colección de solicitudes automáticamente.

openapi: 3.0.3
info:
  title: GeoLogi Flags API
  version: "1.1"
servers:
  - url: https://geo.logihub.tech/api/flags
components:
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    Flag:
      type: object
      properties:
        size: { type: string, enum: [small, normal, large], example: normal }
        path: { type: string, example: /asset/flags/normal/it.png }
        url:  { type: string, example: https://geo.logihub.tech/asset/flags/normal/it.png }
        mime: { type: string, example: image/png }
    FlagItem:
      type: object
      properties:
        iso2: { type: string, example: IT }
        name: { type: string, example: Italy }
        flag:
          $ref: '#/components/schemas/Flag'
    FlagResponse:
      type: object
      properties:
        ok: { type: boolean, example: true }
        data:
          $ref: '#/components/schemas/FlagItem'
    ListResponse:
      type: object
      properties:
        ok: { type: boolean }
        count: { type: integer }
        data:
          type: array
          items: { $ref: '#/components/schemas/FlagItem' }
        paging:
          type: object
          properties:
            limit: { type: integer }
            offset:{ type: integer }
security:
  - ApiKeyHeader: []
  - BearerAuth: []
paths:
  /status:
    get:
      summary: Service status
      responses:
        '200': { description: ok }
  /flag:
    get:
      summary: Get flag by country
      description: Accepts ISO-2, ISO-3 or country name (ES/EN aliases).
      parameters:
        - in: query
          name: country
          required: true
          schema: { type: string, example: Italy }
        - in: query
          name: mode
          schema: { type: string, enum: [json, redirect, raw], default: json }
        - in: query
          name: size
          schema: { type: string, enum: [small, normal, large], default: normal }
      responses:
        '200':
          description: JSON or raw image
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FlagResponse' }
            image/png:
              schema: { type: string, format: binary }
        '302': { description: Redirect to image URL }
        '400': { description: Missing or invalid params }
        '401': { description: Unauthorized }
        '404': { description: Not found }
        '429': { description: Rate limited }
  /list:
    get:
      summary: List flags
      parameters:
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 250, default: 250 }
        - in: query
          name: offset
          schema: { type: integer, minimum: 0, default: 0 }
        - in: query
          name: size
          schema: { type: string, enum: [small, normal, large], default: normal }
      responses:
        '200':
          description: ok
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ListResponse' }
        '401': { description: Unauthorized }
        '429': { description: Rate limited }