Premiers pas avec l'API Vianova

Introduction

L'API de Vianova facilite l'obtention de données riches et fiables sur la micro-mobilité dans votre ville. L'API couvre un large éventail de cas d'utilisation, notamment les historiques, les statuts en temps réel et les agrégats statistiques. L'accès aux données est entièrement sécurisé et conforme au RGPD.

Pour commencer

Créer un compte

L'utilisation de l'API nécessite une authentification, vous devez donc disposer d'un compte Vianova. Votre responsable d'organisation peut vous ajouter à une organisation à l'aide du lien suivant : https://cityscope.vianova.io/settings/users. Vous recevrez un e-mail de confirmation contenant un nom d'utilisateur et un mot de passe que vous devrez modifier lors de votre première connexion. Une fois que vous aurez configuré votre nom d'utilisateur et votre mot de passe, vous serez prêt à commencer ! Vous pouvez également vous connecter ici : https://cityscope.vianova.io/login.

Récupérer des données en envoyant des requêtes

Un résumé de toutes les requêtes possibles est disponible à l'adresse https://developers.vianova.io/. Il fournit l'hôte, les chemins d'accès, les méthodes, les en-têtes, les paramètres, les corps, les modèles et les modèles de réponse pour chaque requête.

Un jeton d'autorisation est nécessaire pour accéder à la plupart des points de terminaison de l'API Vianova. Le jeton d'autorisation est la « clé » qui permet à l'API de protéger de manière sécurisée les informations de votre organisation contre tout accès public et toute personne malveillante.

Ci-dessous, nous décrivons comment obtenir un jeton d'autorisation avec les identifiants de votre utilisateur de plusieurs manières différentes.

Faites votre première demande

Avec le portail OpenAPI

Vous pouvez directement faire des demandes à partir de la documentation disponible à l'adresse https://api.vianova.dev/docs.

Cliquez sur Autoriser à droite.

Entrez votre nom d'utilisateur et votre mot de passe, puis cliquez sur Autoriser, puis sur Fermer.

Avec Postman

Postman est un outil destiné au développement et à la gestion d'API. Il vous permet d'importer facilement nos modèles de requêtes API et de récupérer des données.

Dans Postman, cliquez sur Importer.

Cliquez sur Lien et saisissez le lien vers la documentation de l'API au format Json : https://api.vianova.dev/openapi.json

Dans Collections, ouvrez Hawkeye. Toutes les demandes préremplies y sont disponibles. Vous devez d'abord obtenir un jeton, alors cliquez sur Token. Remplissez le nom d'utilisateur et le mot de passe dans le corps du message, puis cliquez sur Send.

Vous pouvez désormais envoyer la requête de votre choix dans la liste. Modifiez les valeurs dans le corps si nécessaire. Dans Autorisation, sélectionnez Bearer Token et collez le jeton. Dans Params, ajoutez (clé, valeur) = (baseUrl, https://api.vianova.dev) ou directement dans l'environnement.

Avec Python

Tout d'abord, récupérez le jeton de porteur à l'aide d'une requête POST en utilisant vos identifiants de compte (nom d'utilisateur + mot de passe) dans le corps du message.

import requests

import json

 

host = "https://api.vianova.dev"

username = '[email protected]'

password = 'my-password'

 

path = '/token'

address = host + path

token = requests.post(address, data = {'username': username, 'password': password}).json()['access_token']

Vous pouvez désormais effectuer toutes les requêtes que vous souhaitez. Par exemple, pour obtenir le zone_id de votre organisation :

def auth_headers():

  return {'Authorization': 'Bearer ' + token}

zone_id = int(requests.get(host + '/user/', headers = auth_headers()).json()['org'].split('/')[-1])

Données

Après avoir obtenu un jeton JWT, vous devriez pouvoir effectuer tous les appels API avec votre client préféré. Parlons maintenant des sources de données.

Sources

Les fournisseurs de micro-mobilité, tels que les sociétés de location de vélos ou de trottinettes, partagent certaines données relatives à leur flotte. Ces flux comprennent à la fois des informations descriptives intrinsèques (par exemple, le type et l'identifiant de l'appareil) et des données de localisation en temps réel.

Chez Vianova, nous collectons, nettoyons et partageons ces données en toute sécurité avec les villes, dans le respect des normes du RGPD. Vous pouvez ainsi accéder aux données de micro-mobilité en temps réel et historiques de votre ville, enrichies par des informations sur les trajets, les « road-snapping » et des statistiques selon différents critères d'agrégation (par exemple, l'heure, le type d'appareil, le fournisseur, le jour de la semaine).

Ensembles de données : Indicateurs

Le /zone/<zone_id>/metrics Le point de terminaison fournit des statistiques agrégées sur des plages horaires arbitraires. Par exemple, le point de terminaison des métriques peut fournir des moyennes horaires/quotidiennes/hebdomadaires de la taille de la flotte, de la disponibilité et du nombre de trajets sur une période configurable entre une date de début et une date de fin.

Ils sont agrégés en regroupant des paramètres tels que « fournisseur », « type d'appareil », « résolution temporelle ».

metric_type : type de métrique indiqué dans la valeur (par exemple « availability », « fleet_size »)
regroupement : paramètre de regroupement (par exemple « jour_de_la_semaine », « fournisseur »)
grouping_value : valeur prise par le paramètre de regroupement (par exemple « bicycle », « /providers/15 »)
valeur : valeur métrique
heure : date et heure

Ensembles de données : Événements

Le /zone/<zone_id>/events Le point de terminaison renvoie les événements individuels émis par les appareils de toutes les flottes d'une zone. Il permet de « filtrer » les paramètres afin de ne renvoyer que les événements qui vous intéressent, par exemple « tous les événements de dépôt de fournisseurs dans le quartier d'Ixelles à Bruxelles au mois de mai pour les fournisseurs Voi et Bird ». Chaque enregistrement d'événement contient les champs suivants :

event_time : horodatage de l'événement
position : latitude et longitude de l'appareil au moment où cet événement s'est produit
device_type : type d'appareil (par exemple « vélo », « scooter »)
device_state : état de l'appareil (par exemple « disponible », « opérationnel »)
event_type : type d'événement (par exemple « user_pick_up », « low battery »)
fournisseur : lien vers le fournisseur
provider_device_id : identifiant externe de l'appareil, unique par fournisseur
next_position : latitude et longitude de l'appareil lors du prochain événement
next_event_time : horodatage du prochain événement
next_device_state : état suivant de l'appareil
next_event_type : type de l'événement suivant

Étude de cas

Afin de vous aider, nous avons mis en place un espace collaboratif ouvert contenant des exemples de code partagés avec des cas d'utilisation simples déjà couverts par des algorithmes Python :

Colab

Carnet Colab (exemple de code)

N'hésitez pas à nous contacter si vous avez des questions techniques.