O que é a API REST do CartoVista e para que posso usá-la?
O CartoVista tem uma API REST que permitirá que você automatize qualquer uma de suas ações na plataforma, como carregar um conjunto de dados, modificar um conjunto de dados ou parte de um conjunto de dados, excluir um objeto na plataforma, etc.
A API do CartoVista é baseada nos princípios REST. As chamadas à API são feitas por meio de solicitações HTTP, usando os seguintes métodos padrão: GET, POST, DELETE, PATCH.
Essa API REST permite a interoperabilidade com outros sistemas e bancos de dados. Aqui estão alguns exemplos de como ela pode ser usada:
- Atualizar diariamente o site nível a partir de uma fonte de dados pública
- Atualizar ou adicionar novos recursos em um site nível com base em acionadores em um banco de dados
- alterar o conteúdo de uma história automaticamente quando os dados excederem um determinado limite
- exportar estatísticas do espaço de trabalho semanalmente para rastrear o uso de mapas públicos
- importar sua base de usuários para o CartoVista para enviar convites automaticamente
Comece a usar
Autenticar sua solicitação
Você precisará de uma chave de API para começar a usar a API REST do CartoVista. As chaves de API são associadas aos usuários e herdam suas permissões. Você pode usar o tutorial Generate an API Key (Gerar uma chave de API ) da Central de recursos em seu espaço de trabalho para saber como gerar sua chave.
Uma lista de endereços IP externos protege as chaves de API. Portanto, você precisará fazer as chamadas de API do computador cujo IP você registrou. Registre vários endereços IP externos para uma chave de API, listando os IPs separados por ponto e vírgula.
Se quiser evitar o uso da lista de permissões de endereços IP, você pode gerar uma chave secreta e remover o conteúdo da lista de permissões de IP. A chave secreta fica visível apenas temporariamente na plataforma, e você terá que gerá-la novamente se não a salvar em outro lugar.
Você também pode combinar os dois métodos de segurança para ter uma chave secreta e uma lista de permissões de IP. Você precisa de pelo menos um método de segurança para que a chave de API funcione (lista de permissões de IP ou chave secreta).
Para gerar uma chave secreta, clique no usuário para o qual você deseja criar uma chave na guia Users (Usuários ) da plataforma. No painel detalhado do usuário, clique na guia API Key (Chave de API ). Clique no ícone + para gerar uma nova chave.
Digite um endereço IP para gerar a chave.
Depois que a chave for gerada, você poderá copiá-la da plataforma para integrá-la ao seu script. Você também pode gerar uma chave secreta a partir desse painel.
Em suas chamadas de API, você precisará passar o cabeçalho apiKey e o cabeçalho secretKey se tiver gerado um. O cabeçalho secretKey é opcional.
Observe que, se estiver usando serviços de teste de API on-line, como o Postman, você precisará usar a chave secreta e remover a lista de permissões de IP, pois o endereço IP do Postman não é estático.
Identifique a solicitação de que você precisa
O CartoVista usa o Swagger para documentar os pontos de extremidade da API. Na guia Chave de API do painel de detalhes de um usuário, você encontrará o link para a página do Swagger. Você também pode usar o tutorial Gerar uma chave de API do Centro de Recursos em seu espaço de trabalho para chegar à página do Swagger.
O Swagger é útil para que você saiba mais sobre a API, descubra todas as chamadas e métodos disponíveis e experimente-os usando sua chave de API. No entanto, ele não pode ser usado para automatizar suas tarefas.
O Swagger fornece a você a lista de todos os pontos de extremidade, organizados por tópico.
Você pode inserir sua chave de API para testar uma solicitação ou conectar-se à sua conta em outra guia para autenticar suas chamadas swagger. Observe que, se sua chave de API tiver uma chave secreta gerada, você não poderá autenticar suas chamadas swagger inserindo sua chave de API e precisará estar conectado ao seu espaço de trabalho em outra guia.
Clique em um endpoint para ver os detalhes.
Preencha os parâmetros (veja como obter os valores dos parâmetros abaixo) e clique em Try it out. A resposta conterá a solicitação Curl, o corpo da resposta e o código da resposta.
✔️ Agora você pode usar qualquer software capaz de enviar e receber solicitações HTTP para usar a API REST do CartoVista e começar a automatizar suas tarefas.
Parâmetros
Ao usar a API REST em mapas ou dados, você precisará passar o URL ou o corpo
- o tenantUrlCode: esse é o identificador do seu espaço de trabalho. Você pode encontrá-lo na URL do seu espaço de trabalho do CartoVista: cloud.cartovista.com/{tenantUrlCode}/maps.
- o identificador do seu conjunto de dados ou do seu mapa.
Para obter o identificador de um mapa, clique na parte inferior de um cartão de mapa para abrir o painel detalhado do mapa. A guia Informações fornecerá a você o URL do mapa. O identificador é o código de 5 caracteres (números e/ou letras) entre o nome do espaço de trabalho e o nome do mapa:
Para obter o identificador de um nível ou de uma tabela de dados, clique na parte inferior de um cartão de dados na Galeria de dados para abrir o painel detalhado dos dados. A guia Informações fornecerá a você o identificador dos seus dados:
Pacote Pip para Python
Além da página do Swagger, a API também está disponível como um pacote pip para Python. As instruções de instalação, os exemplos de uso e a documentação detalhada estão disponíveis no GitHub: https://github.com/cartovista/cartovista-cloud-restapi-python-clients.