Bienvenido a la API de VereData

La API de VereData es una interfaz REST moderna que proporciona acceso estructurado a datos relevantes sobre Colombia. Nuestra API está diseñada para ser intuitiva y confiable, ofreciendo:

Respuestas en formato JSON para una fácil integración con cualquier plataforma o lenguaje de programación
Autenticación básica robusta que garantiza la seguridad de los datos
Códigos de estado HTTP estándar para una mejor gestión de respuestas
Documentación completa y ejemplos prácticos

URL Base

https://apivd.veredata.co/v1

Todas las solicitudes deben realizarse a través de HTTPS a esta URL base. Asegúrate de incluir tus credenciales de autenticación en cada solicitud para acceder a los endpoints protegidos.

Autenticación

La API de VereData utiliza autenticación Bearer Token para garantizar un acceso seguro a los recursos. Todas las solicitudes deben realizarse a través de HTTPS e incluir un token de autenticación válido en el encabezado.

Cómo autenticarse

Para autenticar tus solicitudes, necesitas:

Incluir el encabezado Authorization con tu token de acceso
Usar HTTPS para todas las llamadas
Especificar el tipo de contenido como JSON

Ejemplo de solicitud


              curl -X GET \
                'https://apivd.veredata.co/v1' \
                -H 'Authorization: Bearer $ACCESS_TOKEN'

Notas importantes

Reemplaza $ACCESS_TOKEN con tu token de acceso personal
Mantén tu token seguro y no lo compartas
Los tokens tienen un período de validez limitado de 1 hora.
Todas las solicitudes sin un token válido recibirán un error 401 Unauthorized

Gestión de usuarios

Crear usuario

Para usar la API de VereData, debes ser un usuario de sistema. Si aún no tienes una cuenta, puedes crear una siguiendo estos pasos:

Inicia sesión en la aplicación.
En el menú de la aplicación, ve a la sección "Seguridad" y luego a "Usuarios". Allí, haz clic en el botón "Crear Usuario".
Completa el formulario con la información del nuevo usuario y activa la opción "¿Usuario de sistema?".
Nota importante: Un usuario de sistema no se puede conectar a la aplicación de VereData.
Al activar la opción "¿Usuario de sistema?", se habilitan dos campos adicionales: Contraseña y Repetir contraseña.
Nota importante: Ambas contraseñas deben coincidir para continuar.
Una vez que se complete el ingreso de la información, haga clic en el botón Guardar. Si los datos son correctos, se descargará un archivo CSV que contiene información sensible del usuario, como la API Key y el Refresh Token.

¡Importante!

Este archivo se genera únicamente una vez y no estará disponible para descarga desde la aplicación. **¡Asegúrese de guardarlo en un lugar seguro!**

Nunca expongas tu clave privada en un repositorio público ni la incluyas directamente en tu código. Asegúrate de gestionarla de manera segura desde tu servidor.

Refrescar y generar un nuevo token

Si tu token de acceso ha caducado, puedes:

Refrescar el token existente
Generar un nuevo token de acceso

Refrescar el token existente

Solicitud


                  curl -X POST \
                    'https://apivd.veredata.co/v1/users/token' \
                    -H 'x-api-key: $API_KEY' \
                    -H 'Content-Type: application/json'
                    -d '{
                      "refresh_token": "$REFRESH_TOKEN"
                    }'

El parámetro $API_KEY corresponde a la información disponible al crear el usuario de sistema.
El parámetro $REFRESH_TOKEN es el código de seguridad utilizado para obtener nuevos tokens de acceso.

Respuesta


                  {
                    "uid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                    "token": "XXXXXXXXXX.XXXXXXXXXX.XXXXXXXXXX",
                    "refresh_token": "XXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXX_XXXXXXXXXX",
                    "expires_in": "3600"
                  }

La respuesta incluye:

uid: Identificador único del usuario.
token: Código de seguridad que identifica al usuario y acceder a los recursos protegidos. Su validez está determinada por el parámetro expires_in.
refresh_token: Código de seguridad utilizado para obtener tokens y el acceso a los recursos y sigan siendo válidos antes del final del período de validez del token.
expires_in: Tiempo de caducidad del token expresado en segundos. De forma predeterminada, el tiempo de caducidad es de 1 hora (3600 segundos).

Errores

400 (bad_request): No se puede o no se procesará la solicitud debido a un error del cliente.
- API key invalido o no enviado en el header de la petición.
- refresh_token invalido o no enviado en el body de la petición.

Generar un nuevo token de acceso

La API de VereData permite crear un nuevo token de acceso (refresh_token) en caso de que el token actual haya expirado. Esta solicitud se realiza enviando el correo electrónico y la contraseña del usuario.

Solicitud


                    curl -X POST \
                      'https://apivd.veredata.co/v1/users/authorize' \
                      -H 'x-api-key: $API_KEY' \
                      -H 'Content-Type: application/json'
                      -d '{
                        "email": "$EMAIL",
                        "password": "$PASSWORD"
                      }'

El parámetro $API_KEY corresponde a la información disponible al crear el usuario de sistema.
El parámetro $EMAIL corresponde al correo electrónico del usuario de sistema.
El parámetro $PASSWORD corresponde a la contraseña del usuario de sistema.

Respuesta


                    {
                      "uid": "XXXXXXXXXXXXXXXXXXXXXXXXXXXX",
                      "token": "XXXXXXXXXX.XXXXXXXXXX.XXXXXXXXXX",
                      "refresh_token": "XXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXX_XXXXXXXXXX",
                      "expires_in": "3600"
                    }

La respuesta incluye:

uid: Identificador único del usuario.
token: Código de seguridad que identifica al usuario y acceder a los recursos protegidos. Su validez está determinada por el parámetro expires_in.
refresh_token: Código de seguridad utilizado para obtener tokens y el acceso a los recursos y sigan siendo válidos antes del final del período de validez del token.
expires_in: Tiempo de caducidad del token expresado en segundos. De forma predeterminada, el tiempo de caducidad es de 1 hora (3600 segundos).

Errores

400 (bad_request): No se puede o no se procesará la solicitud debido a un error del cliente.
- API key invalido o no enviado en el header de la petición.
- username o password invalidos o no enviados en el body de la petición.

Recursos

Scoring

Scoring permite consultar el puntaje de un municipio o vereda creado por VereData y el cliente.

Endpoints

1. Listar scoring

Recupera la lista completa de scorings que el cliente tiene habilitados en el sistema.

Endpoint: GET /v1/scoring?limit=10

Parámetros de consulta

limit (no requerido): Número de scoring a obtener, por default son: 10.

Solicitud


                  curl -X GET \
                    'https://apivd.veredata.co/v1/scoring?limit=10' \
                    -H 'Authorization: Bearer $ACCESS_TOKEN' \
                    -H 'Content-Type: application/json'

Ejemplo de respuesta


                  [
                    {
                      "id": XXX,
                      "nombre": "XXX",
                      "version": XXX,
                      "operacion": XXX,
                      "calificacion": XXX,
                      "fecha_creacion": "XXX",
                      "cliente_id": XXX,
                      "activo": XXX,
                      "scoringconfiguracionmodel_set": [
                        "XXX"
                      ]
                    },
                    // ... más scorings
                  ]

2. Obtener score municipio

Obtiene el valor del score de un municipio.

Endpoint: POST /v1/scoring

Solicitud


                  curl -X GET \
                    'https://apivd.veredata.co/v1/scoring' \
                    -H 'Authorization: Bearer $ACCESS_TOKEN' \
                    -H 'Content-Type: application/json'
                    -d '{
                      "municipio_codigo_dane": $MUNICIPIO_DANE,
                      "score_version": $SCORE_VERSION
                    }'

$MUNICIPIO_DANE: Código dane del municipio.
$SCORE_VERSION: Versión del score (campo "version" del objeto scoring).

Ejemplo de respuesta


                  {
                    "score": X.XXXX
                  }

score: Puntación del municipio consultado.

Errores

400 (bad_request): No se puede o no se procesará la solicitud debido a un error del cliente.
- Municipio código dane invalidos o no enviados en el body de la petición.
- Versión invalido o no enviado en el body de la petición.
401 (Unauthorized): Error del lado del cliente: el servidor requiere que el token se incluya en el encabezado.

3. Obtener scores municipios Colombia

Obtiene el valor del score de todos los municipios (1121) de Colombia y la definición de los rangos de clasificación para categorizar los puntajes.

Endpoint: POST /v1/score/all?version=2

Parámetros de consulta

version (requerido): Número de la versión del score a obtener (campo "version" del objeto scoring).

Ejemplo de solicitud


                  curl -X GET \
                    'https://apivd.veredata.co/v1/score/all?version=$SCORE_VERSION' \
                    -H 'Authorization: Bearer $ACCESS_TOKEN' \
                    -H 'Content-Type: application/json'

$SCORE_VERSION: Versión del score (campo "version" del objeto scoring).

Ejemplo de respuesta


                  {
                    "ranking": {
                        "bajo": {
                            "min": X.XXXX,
                            "max": X.XXXX
                        },
                        "medio": {
                            "min": X.XXXX,
                            "max": X.XXXX
                        },
                        "alto": {
                            "min": X.XXXX,
                            "max": X.XXXX
                        }
                    },
                    "scoring": [
                      {
                        "municipio": "El encanto",
                        "departamento": "Amazonas",
                        "codigo_dane": "91263",
                        "score": X.XXXX,
                        "calificacion": "Bajo"
                      },
                      // ... más scores
                    ]
                  }

score: Puntación del municipio consultado.

Errores

400 (bad_request): No se puede o no se procesará la solicitud debido a un error del cliente.
- Versión invalido o no enviado en el body de la petición.
401 (Unauthorized): Error del lado del cliente: el servidor requiere que el token se incluya en el encabezado.

Variables

Una variable es una unidad fundamental de datos que representa una métrica o indicador específico dentro del sistema VereData. Cada variable está asociada a una fuente de datos y tiene atributos que la describen y categorizan.

Endpoints

1. Listar variables

Obtiene el catálogo completo de variables disponibles en el sistema.

Endpoint: GET /v2/update/variables

Solicitud


                  curl -X GET \
                    'https://apivd.veredata.co/v2/update/variables' \
                    -H 'Authorization: Bearer $ACCESS_TOKEN' \
                    -H 'Content-Type: application/json'

Ejemplo de respuesta


                  [
                    {
                      "id": 1,
                      "table_db": {
                        "name": "Desaparición forzada",
                        "name_table": "desaparicion_forzada",
                        "category": "Conflicto armado",
                        "description": "Son eventos altamente...",
                        "entity": "URV",
                        "link_download": "https://www.datos.gov.co/Inclusi-n-Social-y-Reconciliaci-n/Cifras-de-V-ctimas-por-Hechos-Municipal/9qih-4vkc/about_data",
                        "created": "2023-09-21T20:58:53.350150Z",
                        "source_status_id": 1,
                        "date_last_update": "2024-04-30"
                      },
                      "name_var": "Desaparición Forzada",
                      "name_modelo": "VictimizantesModel",
                      "column_periodo": "periodo",
                      "type_search": "none_filter",
                      "add_division": true,
                      "type_division": "MUNICIPAL",
                      "is_geometry": false,
                      "column_select": "total",
                      "column_process": "sumatoria",
                      "columns_view": {},
                      "category": "conflicto_armado",
                      "is_multiple": false,
                      "is_previous_year": false,
                      "normalize": true,
                      "units": "Desapariciones",
                      "filter_model": {
                        "hecho": [
                          "Desaparición forzada"
                        ]
                      },
                      "is_atributo": false,
                      "column_atributo": {},
                      "tag_state": ""
                    },
                    // ... más variables
                  ]

Estructura del objeto variable

Cada variable en el sistema tiene los siguientes atributos:

id: Identificador único de la variable
table_db: Objeto que contiene información sobre la fuente asociada
- name: Nombre descriptivo de la fuente
- name_table: Nombre técnico de la fuente en el sistema
- category: Categoría temática a la que pertenece la fuente
- description: Descripción detallada de la fuente
- entity: Entidad responsable de los datos
- link_download: URL para descargar los datos
- created: Fecha de creación de la fuente
- source_status_id: ID del estado de la fuente de datos
- date_last_update: Fecha de la última actualización
name_var: Nombre descriptivo de la variable
name_modelo: Nombre del modelo asociado a la variable
column_periodo: Nombre de la columna de período
type_search: Tipo de búsqueda permitida para la variable
add_division: Si se debe agregar una división a la variable
type_division: Tipo de división de la variable (veredal, municipal, departamental)
is_geometry: Si la variable tiene un componente de geometría
column_select: Nombre de la columna a seleccionar
column_process: Tipo de procesamiento a aplicar a la columna
columns_view: Columnas adicionales a mostrar
category: Categoría a la que pertenece la variable
is_multiple: Si la variable tiene múltiples valores
is_previous_year: Si la variable retorna los periodos anteriores al seleccionado
normalize: Si los datos de la variable se pueden obtener normalizados (por presencial municipal (true o false), por cada 100.000 habitantes a nivel municipal)
units: Unidad de la variable
filter_model: Objeto que contiene filtros para la variable
is_atributo: Si la variable es un atributo
column_atributo: Objeto que contiene información sobre la columna de atributo
tag_state: Etiqueta del estado de la variable (nueva, pronto, actualizandose)

Históricos

Los históricos te permiten acceder al historial completo de una variable disponible en VereData.

Endpoints

1. Obtener periodos por variable

Obtiene la lista de periodos disponibles para consultar de una variable.

Endpoint: GET /v2/historic/year?modelo=$MODELO

Parámetros de consulta

modelo (requerido): Nombre de la variable (campo "name_var" del objeto variable)

Ejemplo de solicitud


                    curl -X GET \
                      'https://apivd.veredata.co/v2/historic/year?modelo=$MODELO' \
                      -H 'Authorization: Bearer $ACCESS_TOKEN' \
                      -H 'Content-Type: application/json'

Ejemplo de respuesta


                    {
                      "periodos": [
                        2024,
                        2023,
                        2022,
                        2021,
                        2020,
                        2019,
                        2018,
                        2017,
                        2016,
                        2015,
                        2014,
                        2013,
                        2012,
                        2011,
                        2010
                      ],
                      "name_table": "Acciones Subversivas"
                    }

2. Obtener histórico por variable

Obtiene el histórico de una variable.

Endpoint: POST /v2/historic

Ejemplo de solicitud


                    curl -X POST \
                      'https://apivd.veredata.co/v2/historic' \
                      -H 'Authorization: Bearer $ACCESS_TOKEN' \
                      -H 'Content-Type: application/json'
                      -d '{
                        "municipio_codigo_dane": $MUNICIPIO_DANE,
                        "numero_datos": $NUMERO_DATOS,
                        "datos": [
                          {
                            "modelo": "$MODELO",
                            "variable": "$VARIABLE"
                          }
                        ]
                      }'

$MUNICIPIO_DANE: Código dane del municipio.
$NUMERO_DATOS (opcional): Cantidad de datos a recuperar. Por defecto se recuperán 10 datos.
$MODELO: Nombre del modelo (campo "name_var" del objeto variable).
$VARIABLE: Nombre de la variable (campo "column_select" del objeto variable).

Ejemplo de respuesta

La petición devuelve un arreglo por cada modelo/variable.


                    [
                      {
                        "modelo": "Hectáreas De Coca",
                        "variable": "hectareas",
                        "periodo": [
                          20210101,
                          20200101,
                          20190101,
                          20180101,
                          20170101,
                          20160101
                        ],
                        "datos": [
                          2.488226,
                          2.069585363551,
                          6.8175,
                          12.5320612,
                          7.69889549642,
                          34.93
                        ]
                      }
                    ]

Estructura del objeto histórico

Cada histórico tiene los siguientes atributos:

modelo: Nombre de la variable (campo "name_var" del objeto variable).
variable: Nombre de la columna a seleccionar (campo "column_select" del objeto variable).
periodo: Lista de periodos, la respuesta puede ser en estos tres (3) formatos: YYYY, YYYYMM, YYYYMMDD.
datos: Lista con la información de cada periodo.

Errores

400 (bad_request): No se puede o no se procesará la solicitud debido a un error del cliente.
- municipio código dane Inválido o no proporcionado en el cuerpo de la solicitud.
- datos El arreglo de objetos con formato {"modelo" - "variable"} es inválido o no fue proporcionado en el cuerpo de la solicitud.
401 (Unauthorized): Error del lado del cliente: el servidor requiere que el token se incluya en el encabezado.

Mapas

Próximamente

Bienvenido a la API de VereData

URL Base

Autenticación

Cómo autenticarse

Ejemplo de solicitud

Notas importantes

Gestión de usuarios

Crear usuario

¡Importante!

Refrescar y generar un nuevo token

Refrescar el token existente

Solicitud

Respuesta

La respuesta incluye:

Errores

Generar un nuevo token de acceso

Solicitud

Respuesta

La respuesta incluye:

Errores

Recursos

Scoring

Endpoints

1. Listar scoring

Parámetros de consulta

Solicitud

Ejemplo de respuesta

2. Obtener score municipio

Solicitud

Ejemplo de respuesta

Errores

3. Obtener scores municipios Colombia

Parámetros de consulta

Ejemplo de solicitud

Ejemplo de respuesta

Errores

Variables

Endpoints

1. Listar variables

Solicitud

Ejemplo de respuesta

Estructura del objeto variable

Históricos

Endpoints

1. Obtener periodos por variable

Parámetros de consulta

Ejemplo de solicitud

Ejemplo de respuesta

2. Obtener histórico por variable

Ejemplo de solicitud

Ejemplo de respuesta

Estructura del objeto histórico

Errores

Mapas