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
Bash
Copy

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:

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

Ejemplo de solicitud


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

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:

  1. Inicia sesión en la aplicación.
  2. 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".
    Crear usuario de sistema VereData
  3. 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.

    Crear usuario de sistema VereData
  4. 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.

    Crear usuario de sistema VereData

  5. 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.

Refrescar y generar un nuevo token

Si tu token de acceso ha caducado, puedes:

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"
                    }'
Bash
Copy
  • 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"
                  }
JSON
Copy
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"
                      }'
Bash
Copy
  • 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"
                    }
JSON
Copy
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'
Bash
Copy
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
                  ]
JSON
Copy
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
                    }'
Bash
Copy
  • $MUNICIPIO_DANE: Código dane del municipio.
  • $SCORE_VERSION: Versión del score (campo "version" del objeto scoring).
Ejemplo de respuesta

                  {
                    "score": X.XXXX
                  }
JSON
Copy
  • 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'
Bash
Copy
  • $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
                    ]
                  }
JSON
Copy
  • 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'
Bash
Copy
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
                  ]
JSON
Copy
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'
Bash
Copy
Ejemplo de respuesta

                    {
                      "periodos": [
                        2024,
                        2023,
                        2022,
                        2021,
                        2020,
                        2019,
                        2018,
                        2017,
                        2016,
                        2015,
                        2014,
                        2013,
                        2012,
                        2011,
                        2010
                      ],
                      "name_table": "Acciones Subversivas"
                    }
JSON
Copy
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"
                          }
                        ]
                      }'
Shell
Copy
  • $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
                        ]
                      }
                    ]
JSON
Copy
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