API para consultar el puesto de votación por cédula en Colombia
PlacApi devuelve, con la cédula de una persona, el lugar donde le corresponde votar según el censo electoral de la Registraduría Nacional: el nombre oficial del puesto, su dirección, el número de mesa, el municipio y el departamento, el código DIVIPOL con el que la propia Registraduría publica logística y resultados, y las coordenadas del sitio con un enlace de navegación cuando la fuente lo tiene georreferenciado. Trae además fechaInscripcion, que es desde cuándo la persona figura en ese puesto. No es un servicio estacional: responde el lugar de votación vigente también fuera de calendario electoral.
¿No eres desarrollador? Consulta el RUNT por placa aquí sin escribir código.
Qué problema resuelve
El consultador del censo electoral es una página con reCAPTCHA pensada para que una persona mire su propio puesto, no para que un sistema resuelva miles. Quien organiza transporte el día de elecciones, valida la residencia electoral de sus afiliados o cruza una base de datos contra el censo termina copiando cédulas a mano en un formulario. PlacApi encapsula esa consulta en un endpoint REST que responde en JSON y se puede llamar en lote.
Para quién sirve
Campañas y equipos de logística electoral que organizan transporte y puestos de mando, sindicatos, cajas de compensación y empresas que verifican la residencia electoral de sus afiliados, medios que arman herramientas de consulta ciudadana, y desarrolladores que necesitan cruzar una base de cédulas contra el censo.
Datos requeridos
- docType — solo CC. El censo electoral es de ciudadanos colombianos y no maneja otro tipo de documento; cualquier otro valor responde 400 sin cobrar y sin tocar la fuente.
- docNumber — número de cédula. Alias aceptado: doc.
Fuentes y cobertura
- Censo electoral de la Registraduría NacionalConsultador de puesto de votación del censo electoral. Es el registro que define dónde vota cada ciudadano inscrito y de dónde salen el puesto, la mesa y el código DIVIPOL.
Qué resuelve el código DIVIPOL y por qué importa
El campo codigoPuesto no es un identificador interno de PlacApi: es el código DIVIPOL del puesto, el mismo con el que la Registraduría publica la logística electoral y los resultados por puesto. Sirve para cruzar la respuesta contra los archivos oficiales sin tener que emparejar nombres de colegios escritos de dieciocho maneras distintas.
fechaInscripcion dice desde cuándo la persona figura en ese puesto. Es el campo que delata un traslado reciente, que es justo lo que se quiere ver cuando se valida residencia electoral y no solo ubicación.
Coordenadas y enlace de navegación
Cuando la fuente tiene el puesto georreferenciado, la respuesta incluye ubicacion con lat, lng y un mapsUrl listo para abrir la ruta. No todos los puestos están georreferenciados en el origen: cuando no lo están, el bloque no viene, y eso es la fuente diciendo que no lo tiene, no un error de la consulta.
Dos formas distintas de no tener puesto
La fuente distingue entre un documento que no figura en el censo y uno que tiene una novedad que lo saca de él —cédula cancelada por muerte, cédula no expedida—. Las dos responden 404 con el mensaje textual del registro y ninguna de las dos cobra.
Se separan a propósito y no se venden como si fueran lo mismo: el estado de una cédula es otra pregunta, con otra fuente y otro precio. Devolver «no está en el censo» cuando lo que pasó es que la cédula fue cancelada sería cobrar por un dato que no se consultó.
¿Cómo consultar el puesto de votación por cédula desde un sistema?
Con una llamada POST a /api/puesto-votacion enviando docType CC y docNumber. La respuesta trae el puesto, la dirección, la mesa, el municipio, el departamento, el código DIVIPOL y, cuando existe, las coordenadas del sitio.
¿Funciona fuera de época de elecciones?
Sí. La consulta devuelve el lugar de votación vigente en el censo electoral y responde también fuera de calendario electoral, no solo en los meses previos a una votación.
Ejemplo de solicitud
POST https://placapi.com/api/puesto-votacion. Autenticación por API key en el header x-api-key. Los datos del ejemplo son ficticios.
curl -X POST 'https://placapi.com/api/puesto-votacion' \
-H 'x-api-key: pk_live_TU_CLAVE' \
-H 'content-type: application/json' \
-d '{"docType":"CC","docNumber":"1020304050"}'Ejemplo de respuesta
Respuesta JSON (fragmento con los campos de esta consulta; la API integral devuelve todas las fuentes en el mismo objeto).
{
"source": "puesto-votacion",
"status": "info",
"data": {
"documento": "1020304050",
"departamento": "VALLE",
"municipio": "CALI",
"puesto": "INSTITUCION EDUCATIVA EJEMPLO",
"direccion": "CALLE 00 # 00-00",
"mesa": "24",
"codigoPuesto": "310019914",
"fechaInscripcion": "2026-02-07",
"ubicacion": {
"lat": 3.35393,
"lng": -76.523,
"mapsUrl": "https://www.google.com/maps/dir/?api=1&destination=3.35393,-76.52300"
}
}
}Explicación campo por campo
| Campo | Tipo | Descripción |
|---|---|---|
| puesto | string | Nombre oficial del puesto de votación, tal como lo escribe el censo electoral. |
| direccion | string | Dirección del puesto. |
| mesa | string | Número de mesa asignado dentro de ese puesto. |
| municipio, departamento | string | Ubicación administrativa del puesto. |
| codigoPuesto | string | Código DIVIPOL del puesto: el identificador con el que la Registraduría publica logística y resultados. Es lo que permite cruzar la respuesta contra los archivos oficiales. |
| fechaInscripcion | string | Desde cuándo la persona figura inscrita en ese puesto. Delata un traslado reciente. |
| ubicacion | object | lat, lng y mapsUrl con la ruta lista. Solo cuando la fuente tiene el puesto georreferenciado; si no lo tiene, el bloque no viene. |
Tiempo de respuesta
Alrededor de medio segundo en régimen normal. La primera consulta de cada réplica paga unos 23 segundos porque hay que resolver el captcha de la fuente; el token que sale de ahí se reutiliza para las siguientes, así que ese costo se paga una vez y no por consulta.
Precio y cobro
1 crédito por consulta con datos, desde 349 COP. El precio por crédito baja por volumen: 349 COP desde 30, 249 COP desde 1.000, 149 COP desde 5.000, 139 COP desde 10.000, 119 COP desde 20.000, 99 COP desde 50.000. Los créditos se compran por adelantado (mínimo 30 = 10.470 COP), no vencen y no hay mensualidad. El mismo precio aplica por la web y por API. Solo se cobra cuando la consulta devuelve datos; por API, las consultas sin resultado (404) tienen 10 gratis al mes por cada tipo de respuesta sin datos y después cobran igual.
Caché y actualización
Largo, porque el puesto de una persona solo cambia cuando se inscribe en otro. La fecha de inscripción viene en la respuesta, así que se puede detectar el traslado sin volver a consultar a ciegas.
Seguridad y privacidad
La placa y el documento se usan solo para ejecutar la consulta; el resultado queda en caché temporal. No se almacenan datos de tarjetas (los pagos los procesa Wompi). Ver privacidad y seguridad.
Limitaciones y posibles errores
- Solo cédula de ciudadanía. Cualquier otro tipo de documento responde 400 tipo_documento_no_soportado sin cobrar y sin consultar a la fuente.
- Un documento que no figura en el censo responde 404 y NO cobra. Acá el producto es el puesto: si no vino, no se entregó nada.
- Una cédula con novedad (cancelada por muerte, no expedida) también responde 404, con el mensaje textual del registro. No se convierte en un «sin puesto» genérico ni se cobra como si lo fuera.
- No devuelve si la persona ya votó, ni su historial de votación, ni si fue designada jurado: eso no está en el consultador del censo.
- El bloque ubicacion depende de que la fuente tenga el puesto georreferenciado, y no todos lo están.
Códigos de error del endpoint (401, 402, 429, 5xx) en la referencia de errores.
Otras preguntas frecuentes
¿Se puede consultar con cédula de extranjería o pasaporte?
+
No. El censo electoral es de ciudadanos colombianos y solo maneja cédula de ciudadanía. Cualquier otro tipo de documento se rechaza con 400 y no consume crédito.
¿Qué pasa si la cédula no está en el censo?
+
Se responde 404 y no se cobra. Lo mismo si la cédula tiene una novedad que la saca del censo, como una cancelación por muerte: en ese caso viene el mensaje textual del registro.
¿Dice si la persona fue designada jurado de votación?
+
No. El consultador del censo devuelve dónde vota la persona, no si quedó sorteada como jurado; esa designación se publica por otro canal y no está en esta fuente.
¿Cuánto cuesta?
+
1 crédito por consulta que devuelve puesto. Las consultas sin resultado no cobran.
Seguir explorando
Última revisión: 23 de agosto de 2026 · Versión de la API: v1 · Fuentes y metodología