Find a Dominican place

Search for a province, municipality, barrio, or other place and see where it belongs in the territorial hierarchy.

The explorer starts with Gazcue. Change the name or filter by place type when several areas share a name. Choose a result only after checking its type and parent areas.

Understand the result

Each match has the information you need to store and display it correctly:

id is the stable Indexa place identifier.
name is the place name, while kind identifies its level, such as province, municipality, or barrio.
ancestors lists its parent areas from the country down to its immediate parent.

Save the chosen id and the response's catalog.releaseId. Records can be provisional, so check the catalog date and coverage limits before treating them as current legal geography.

Add place search to your app

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(`Place search failed: ${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,
}));

// For the next page, keep the same filters and catalog release.
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(`Next page failed: ${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,
  })));
}

For a picker, wait briefly after typing, cancel superseded requests, and apply only the latest response. Never select the first result automatically: duplicate place names are common.

Narrow the search or build dependent dropdowns

Add kind=municipality to return one territorial level. Add within={placeId} when you already know the parent area and want results only inside it.

For linked dropdowns, request /v1/places/{placeId}/children. Clear every child selection when its parent changes. Keep the original kind even when your interface uses a simpler label.

If you have an official code, call /v1/places/resolve?scheme=…&code=…. Keep the code as a string so leading zeroes are preserved. A code without its scheme is incomplete, and matches[] can contain more than one place.

Load more results and handle errors

When nextCursor is present, repeat the same filters and add that cursor. Keep the same catalog release while paging so the result set does not change between requests. You can also ask the user for a more specific name instead of loading every match.

An empty places[] means there was no match for that name and scope; it does not prove the place does not exist. HTTP 400 means a parameter needs correction. HTTP 404 can mean an unknown place or release. HTTP 503 means the catalog cannot serve a reliable response right now. Keep error.requestId when reporting a problem.

Read the error reference for response shapes and recovery guidance.

Explore the locations API →