Buscar una localidad dominicana

Busca una provincia, un municipio, un barrio u otra localidad y revisa a qué áreas pertenece.

El explorador comienza con Gazcue. Cambia el nombre o filtra por tipo cuando varias localidades se llamen igual. Antes de elegir, revisa el tipo y las áreas superiores.

Entender el resultado

Cada coincidencia incluye los datos necesarios para guardarla y mostrarla correctamente:

id es el identificador estable de la localidad en Indexa.
name contiene el nombre y kind indica el nivel, por ejemplo provincia, municipio o barrio.
ancestors muestra las áreas superiores, desde el país hasta el área inmediata.

Guarda el id elegido y el catalog.releaseId de la respuesta. Algunos registros son provisionales. Revisa la fecha del catálogo y los límites de cobertura antes de usarlos como división territorial vigente.

Agregar la búsqueda a tu aplicación

const apiOrigin = '__API_ORIGIN__';
const query = new URLSearchParams({ q: 'Gazcue', limit: '10' });
const response = await fetch(`${apiOrigin}/v1/places/search?${query}`);
if (!response.ok) throw new Error(`La búsqueda de localidades falló: ${response.status}`);
const { catalog, places, nextCursor } = await response.json();

const suggestions = places.map(place => ({
  id: place.id,
  label: [place.name, ...place.ancestors.map(parent => parent.name)].join(' · '),
  kind: place.kind,
  releaseId: catalog.releaseId,
}));

// Para la siguiente página, conserva los filtros y la versión del catálogo.
if (nextCursor) {
  query.set('cursor', nextCursor);
  query.set('release', catalog.releaseId);
  const nextResponse = await fetch(`${apiOrigin}/v1/places/search?${query}`);
  if (!nextResponse.ok) throw new Error(`Falló la página siguiente: ${nextResponse.status}`);
  const nextPage = await nextResponse.json();
  suggestions.push(...nextPage.places.map(place => ({
    id: place.id,
    label: [place.name, ...place.ancestors.map(parent => parent.name)].join(' · '),
    kind: place.kind,
    releaseId: nextPage.catalog.releaseId,
  })));
}

En un campo con sugerencias, espera unos milisegundos después de escribir, cancela las consultas anteriores y usa solo la respuesta más reciente. No elijas la primera coincidencia automáticamente: muchas localidades comparten el mismo nombre.

Limitar la búsqueda o crear selectores dependientes

Agrega kind=municipality para buscar un solo nivel territorial. Usa within={placeId} cuando ya conozcas el área superior y quieras resultados únicamente dentro de ella.

Para crear selectores dependientes, consulta /v1/places/{placeId}/children. Cuando cambie un área, borra las selecciones que dependan de ella. Conserva el kind original aunque tu interfaz muestre una palabra más sencilla.

Si tienes un código oficial, llama a /v1/places/resolve?scheme=…&code=…. Guarda el código como texto para no perder ceros iniciales. Un código sin su scheme está incompleto y matches[] puede devolver más de una localidad.

Cargar más resultados y gestionar errores

Si recibes nextCursor, repite los mismos filtros y agrega ese cursor. Usa la misma versión del catálogo durante la paginación para que los resultados no cambien entre consultas. También puedes pedir un nombre más específico en lugar de cargar todas las coincidencias.

Un places[] vacío significa que no hubo coincidencias para ese nombre y alcance; no demuestra que la localidad no exista. HTTP 400 indica que debes corregir un parámetro. HTTP 404 puede indicar una localidad o versión desconocida. HTTP 503 significa que el catálogo no puede responder de forma confiable en ese momento. Conserva error.requestId cuando reportes un problema.

Consulta la referencia de errores (en inglés) para ver las respuestas y acciones recomendadas.

Explorar la API de localidades →