Introducción

Esta API de Localidades te permite obtener información sobre provincias, localidades y códigos postales. Puedes buscar por tipo (ej. provincia o localidad), nombre o directamente por un código postal.

A continuación, verás cómo autenticarte, cómo consumir el endpoint principal y un demo interactivo para probarlo.

Autenticación

Para realizar peticiones, debes incluir la cabecera X-API-KEY con el valor de tu clave personal. Si aún no la tienes, solicítala en la parte superior de la página mediante el botón Solicitar API Key. 

GET /v1/api/buscar?query={texto}
Host: api-localidadcp.ghi-web.com
X-API-KEY: TU_API_KEY

Endpoints

1. Búsqueda Unificada

Este es el único endpoint disponible para realizar búsquedas. Puedes buscar por nombre, tipo o código postal utilizando el siguiente formato: 

GET https://api-localidadcp.ghi-web.com/v1/api/buscar?query={texto}
Encabezados:
  X-API-KEY: tu_api_key

Respuesta (JSON):
{
  "tipo": "Provincia",
  "nombre": "Buenos Aires",
  "localidades": [
    {
      "id": 1,
      "nombre": "11 DE SEPTIEMBRE",
      "codigo_postal": "1657"
    },
    {
      "id": 2,
      "nombre": "12 DE AGOSTO",
      "codigo_postal": "2701"
    },
    ...
  ]
}

Reemplaza {texto} por el valor que deseas buscar (ej. Córdoba, Villa María o 1900).

2. Alternativas para Consumir la API

A continuación, se presentan varias formas de consumir el endpoint de búsqueda utilizando diferentes lenguajes y tecnologías:

a. Usando cURL

curl -X GET "https://api-localidadcp.ghi-web.com/v1/api/buscar?query=Córdoba" \
 -H "X-API-KEY: TU_API_KEY"

b. Usando JavaScript (Fetch API)

fetch('https://api-localidadcp.ghi-web.com/v1/api/buscar?query=Córdoba', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'TU_API_KEY'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

c. Usando JavaScript (Axios)

import axios from 'axios';

axios.get('https://api-localidadcp.ghi-web.com/v1/api/buscar', {
  params: { query: 'Córdoba' },
  headers: { 'X-API-KEY': 'TU_API_KEY' }
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('Error:', error);
});

d. Usando TypeScript (Axios)

import axios from 'axios';

interface Localidad {
  id: number;
  nombre: string;
  codigo_postal: string;
}

interface RespuestaProvincia {
  tipo: string;
  nombre: string;
  localidades: Localidad[];
}

axios.get('https://api-localidadcp.ghi-web.com/v1/api/buscar', {
  params: { query: 'Córdoba' },
  headers: { 'X-API-KEY': 'TU_API_KEY' }
})
.then(response => {
  const resultados = response.data;
  console.log(resultados);
})
.catch(error => {
  console.error('Error:', error);
});

e. Usando Node.js (Axios)

const axios = require('axios');

const url = 'https://api-localidadcp.ghi-web.com/v1/api/buscar';
const params = { query: 'Córdoba' };
const headers = { 'X-API-KEY': 'TU_API_KEY' };

axios.get(url, { params, headers })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error('Error:', error);
  });

f. Usando Python (requests)

import requests

url = "https://api-localidadcp.ghi-web.com/v1/api/buscar"
params = {
    "query": "Córdoba"
}
headers = {
    "X-API-KEY": "TU_API_KEY"
}

response = requests.get(url, params=params, headers=headers)

if response.status_code == 200:
    data = response.json()
    print(data)
else:
    print(f"Error: {response.status_code}")

g. Usando Python (aiohttp)

import aiohttp
import asyncio

async def fetch_data(query, api_key):
    url = "https://api-localidadcp.ghi-web.com/v1/api/buscar"
    headers = {
        "X-API-KEY": api_key
    }
    params = {
        "query": query
    }
    async with aiohttp.ClientSession() as session:
        async with session.get(url, headers=headers, params=params) as response:
            if response.status == 200:
                data = await response.json()
                print(data)
            else:
                print(f"Error: {response.status}")

# Ejecutar la función
asyncio.run(fetch_data("Córdoba", "TU_API_KEY"))

h. Usando Ruby (Net::HTTP)

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://api-localidadcp.ghi-web.com/v1/api/buscar?query=Córdoba")
request = Net::HTTP::Get.new(uri)
request["X-API-KEY"] = "TU_API_KEY"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

if response.code.to_i == 200
  data = JSON.parse(response.body)
  puts data
else
  puts "Error: #{response.code}"
end

i. Usando Go (net/http)

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

type Localidad struct {
    ID           int    `json:"id"`
    Nombre       string `json:"nombre"`
    CodigoPostal string `json:"codigo_postal"`
}

type RespuestaProvincia struct {
    Tipo        string      `json:"tipo"`
    Nombre      string      `json:"nombre"`
    Localidades []Localidad `json:"localidades"`
}

func main() {
    url := "https://api-localidadcp.ghi-web.com/v1/api/buscar?query=Córdoba"
    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Add("X-API-KEY", "TU_API_KEY")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)
    if resp.StatusCode == 200 {
        var respuesta RespuestaProvincia
        err := json.Unmarshal(body, &respuesta)
        if err != nil {
            fmt.Println("Error al parsear JSON:", err)
            return
        }
        fmt.Println("Tipo:", respuesta.Tipo)
        fmt.Println("Nombre:", respuesta.Nombre)
        fmt.Println("Localidades:")
        for _, loc := range respuesta.Localidades {
            fmt.Printf("  - %s (CP: %s)\n", loc.Nombre, loc.CodigoPostal)
        }
    } else {
        fmt.Printf("Error: %s\n", resp.Status)
    }
}

j. Usando Postman

Para usar Postman, sigue estos pasos:

  1. Abre Postman.
  2. Selecciona el método GET.
  3. Ingresa la URL:
    4. https://api-localidadcp.ghi-web.com/v1/api/buscar?query=Córdoba
  4. Ve a la pestaña Headers y agrega:
    • Key: X-API-KEY
    • Value: TU_API_KEY
  5. Presiona Send y revisa la respuesta en formato JSON.

Demo Interactiva

A continuación, puedes probar el endpoint de búsqueda ingresando cualquier criterio (ej. provincia, localidad o código postal):