¿Qué es la API REST de CartoVista y para qué puedo utilizarla?
CartoVista dispone de una API REST que te permitirá automatizar cualquiera de tus acciones en la plataforma, como cargar un conjunto de datos, modificar un conjunto de datos o parte de él, eliminar un objeto de la plataforma, etc.
La API de CartoVista se basa en los principios REST. Las llamadas a la API se realizan mediante peticiones HTTP, utilizando los siguientes métodos estándar GET, POST, DELETE, PATCH.
Esta API REST permite la interoperabilidad con otros sistemas y bases de datos. Aquí tienes algunos ejemplos de cómo puede utilizarse:
- actualizar diariamente un capa a partir de una fuente de datos pública
- actualizar o añadir nuevas funciones en un capa basándose en desencadenantes de una base de datos
- cambiar automáticamente el contenido de una historia cuando los datos superen un determinado umbral
- exportar semanalmente las estadísticas del espacio de trabajo para hacer un seguimiento del uso de los mapas públicos
- importa tu base de usuarios a CartoVista para enviar invitaciones automáticamente
Empieza
Autentifica tu solicitud
Necesitarás una clave API para empezar a utilizar la API REST de CartoVista. Las claves API están asociadas a los usuarios y heredan sus permisos. Puedes utilizar el tutorial Generar una clave API del Centro de Recursos de tu espacio de trabajo para aprender a generar tu clave.
Una lista de direcciones IP externas asegura las Claves API. Por tanto, tendrás que realizar las llamadas a la API desde el ordenador cuya IP hayas registrado. Registra varias direcciones IP externas para una Clave API enumerando las IP separadas por punto y coma.
Si quieres evitar el uso de la lista blanca de direcciones IP, puedes generar una clave secreta y eliminar el contenido de la lista blanca de direcciones IP. La clave secreta sólo es visible temporalmente en la plataforma, y tendrás que regenerarla si no la guardas en otro lugar.
También puedes combinar los dos métodos de seguridad para tener tanto una clave secreta como una lista blanca de IP. Necesitas al menos 1 método de seguridad para que la clave API funcione (lista blanca de IP o clave secreta).
Para generar una clave secreta, haz clic en el usuario para el que quieres crear una clave en la pestaña Usuarios de la plataforma. En el panel detallado del usuario, haz clic en la pestaña Clave API . Haz clic en el icono + para generar una nueva clave.
Introduce una dirección IP para generar la clave.
Una vez generada la clave, puedes copiarla desde la plataforma para integrarla en tu script. También puedes generar una clave secreta desde este panel.
En tus llamadas a la API, tendrás que pasar el encabezado apiKey, y el encabezado secretKey si has generado uno. La cabecera secretKey es opcional.
Ten en cuenta que si utilizas servicios de prueba de API en línea como Postman, tendrás que utilizar la clave secreta y eliminar la lista blanca de IP, ya que la dirección IP de Postman no es estática.
Identifica la solicitud que necesitas
CartoVista utiliza Swagger para documentar los puntos finales de la API. En la pestaña Clave API del panel de detalles de un usuario, encontrarás el enlace a la página Swagger. También puedes utilizar el tutorial Generar una Clave API del Centro de Recursos de tu espacio de trabajo para llegar a la página Swagger.
Swagger es útil para saber más sobre la API, conocer todas las llamadas y métodos disponibles, y probarlos utilizando tu clave de API. Sin embargo, no puede utilizarse para automatizar tus tareas.
Swagger te da la lista de todos los puntos finales, organizados por temas.
Puedes introducir tu Clave API para probar una solicitud o conectarte a tu cuenta en otra pestaña para autenticar tus llamadas swagger. Ten en cuenta que si tu Clave API tiene una clave secreta generada, no podrás autenticar tus llamadas swagger introduciendo tu Clave API, y tendrás que conectarte a tu espacio de trabajo en otra pestaña.
Haz clic en un punto final para ver los detalles.
Rellena los parámetros (consulta más abajo cómo obtener los valores de los parámetros), y haz clic en Probar. La respuesta contendrá la petición Curl, el cuerpo de la respuesta y el código de respuesta.
✔️ Ahora puedes utilizar cualquier software capaz de enviar y recibir peticiones HTTP para utilizar la API REST de CartoVista y empezar a automatizar tus tareas.
Parámetros
Cuando utilices la API REST en mapas o datos, tendrás que pasar la URL o el cuerpo
- el código tenantUrlCode: es el identificador de tu espacio de trabajo. Puedes encontrarlo en la URL de tu espacio de trabajo CartoVista: cloud.cartovista.com/{tenantUrlCode}/maps.
- el identificador de tu conjunto de datos o de tu mapa.
Para obtener el identificador de un mapa, haz clic en la parte inferior de una tarjeta de mapa para abrir el panel detallado del mapa. La pestaña Información te dará la URL del mapa. El identificador es el código de 5 caracteres (números y/o letras) que se encuentra entre el nombre del espacio de trabajo y el nombre del mapa:
Para obtener el identificador de un capa o de una tabla de datos, haz clic en la parte inferior de una ficha de datos de la Galería de Datos para abrir el panel detallado de los datos. La pestaña Información te dará el identificador de tus datos:
Paquete Pip para Python
Además de la página Swagger, la API también está disponible como paquete pip para Python. Las instrucciones de instalación, los ejemplos de uso y la documentación detallada están disponibles en GitHub: https://github.com/cartovista/cartovista-cloud-restapi-python-clients.