Tu Lugar API

Inicio rápido

No necesitás API key. Probalo ahora mismo:

# Search apartments for sale in Asunción
curl "https://tulugar.com/api/v1/listings?city=Asunci%C3%B3n&listing_type=sale&property_type=apartment&limit=3"

# Get market summary
curl "https://tulugar.com/api/v1/market/summary?city=Asunci%C3%B3n"

# List all countries
curl "https://tulugar.com/api/v1/locations/countries"

Flujos comunes

Encadená llamadas a la API para resolver tareas típicas. Este ejemplo busca departamentos en venta en un barrio específico.

curl "https://tulugar.com/api/v1/locations/countries"
# Response: [{ "name": "Paraguay", "listing_count": 2500 }, ...]

curl "https://tulugar.com/api/v1/locations/cities?country=Paraguay"
# Response: [{ "name": "Asunción", "listing_count": 1200 }, ...]

curl "https://tulugar.com/api/v1/locations/neighborhoods?city=Asunci%C3%B3n"
# Response: [{ "name": "Villa Morra", "listing_count": 245 }, ...]

curl "https://tulugar.com/api/v1/listings?city=Asunci%C3%B3n&neighborhood=Villa+Morra&listing_type=sale&property_type=apartment&limit=10"

Formato de respuesta

{
  "data": [ ... ],
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-10T..."
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "city is required",
    "status": 400
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

Autenticación

Los endpoints de lectura son públicos, sin key. Los endpoints de la API de agente (escritura) requieren un token de acceso OAuth 2.1 (authorization code + PKCE). La forma más simple de obtener uno es agregar el conector de Tu Lugar en Claude u otro cliente MCP: ejecuta todo el flujo por vos. Las integraciones directas usan el flujo estándar que se describe abajo. Enviá el token como encabezado bearer:

Authorization: Bearer YOUR_ACCESS_TOKEN

Scopes

Flujo de autorización (integraciones directas)

1. Obtené la metadata de descubrimiento desde los endpoints .well-known de abajo.
2. Registrá un cliente mediante Dynamic Client Registration (RFC 7591) en POST /api/oauth/register.
3. Enviá al usuario a /api/oauth/authorize con un desafío PKCE S256; inicia sesión y da su consentimiento.
4. Canjeá el código devuelto en POST /api/oauth/token por un token de acceso + refresh.
5. Llamá a la API con Authorization: Bearer. Los refresh tokens rotan con cada uso.

Endpoints de descubrimiento

Propiedades

Buscá, filtrá y obtené propiedades inmobiliarias.

Proyectos

Proyectos en desarrollo (torres residenciales, barrios cerrados, etc.). Por defecto solo se devuelven los proyectos con unidades disponibles, ordenados con los verificados primero.

Empresas

Inmobiliarias y desarrolladoras.

Agentes

Agentes inmobiliarios y profesionales.

Ubicaciones

Países, ciudades y barrios con la cantidad de avisos.

Datos del mercado

Estadísticas agregadas del mercado y datos de alquiler temporario.

Calculadoras

Calculadoras de finanzas inmobiliarias, agnósticas de moneda y adaptadas a Paraguay. Pensadas para uso por IA; sin autenticación.

API de agente (escritura)

Endpoints autenticados para que los agentes creen y gestionen sus propios avisos. Todos los endpoints de escritura requieren un token bearer OAuth 2.1 con el scope indicado en cada fila (ver Autenticación). Las escrituras de avisos pasan por moderación automática antes de hacerse públicas.

Límites y uso justo