Afin de mener à bien un traitement de géocodage de masse, l’ordonnancement des routes d’API présentées dans le swagger doit être envisagé comme suit :

1. Exécution de la route de création d’un projet (POST /async/projects).
2. En sortie récupération de l’identifiant (élément JSON id dans la réponse) et du jeton (élément JSON token dans la réponse) associé au projet.
3. (ou 4.) Cette étape peut être permutée avec la suivante. Dépôt du fichier (PUT /async/projects/{projectId}/input-file).
   • Bien spécifier sur cet appel un header Authorization Token mon_token_projet où mon_token_projet correspond à la valeur récupérée en étape 2.
   • récupération en sortie du token associé au fichier déposé pour téléchargement ultérieur de ce dernier.
4. (ou 3.) Définition des paramètres du traitement.
   • Bien spécifier sur cet appel un header Authorization Token mon_token_projet où mon_token_projet correspond à la valeur récupérée en étape 2.
   • La rubrique indexes définit le type de géocodage : address pour un géocodage d’adresses postales, poi pour un géocodage sur les points d’intérêt et parcel pour un géocodage de codes parcellaires.
   • columns définit les colonnes du fichier livré qui vont être concaténées pour produire l’adresse complète à géocoder. Les champs doivent être fournis dans l’ordre pour produire en sortie une adresse du type 24 rue de la Libération 96260 Trifouilly les Oies.
   • les paramètres type à number présentés ensuite dans le swagger correspondent à des critères de filtrage possible pour le géocodage. Par exemple, si le fichier livré contient un champ code_insee il est possible de filtrer les résultats du géocodage en fonction de ce champ en indiquant dans le pipeline : "citycode": "code_insee".
5. Lancer le géocodage (POST /async/projects/{projectId}/start).
   • Bien spécifier sur cet appel un header Authorization Token mon_token_projet où mon_token_projet correspond à la valeur récupérée en étape 2.
6. Exécuter de manière cyclique l’état du traitement (GET /async/projects/{projectId}).
   • Bien spécifier sur cet appel un header Authorization Token mon_token_projet où mon_token_projet correspond à la valeur récupérée en étape 2.
   • Le traitement sera terminé lorsque le paramètre JSON de la réponse status vaudra completed.
   • Dès lors récupérer en sortie le token du fichier de sortie contenu dans le paramètre JSON token inclus dans l’objet outputFile.
7. Récupérer le fichier géocodé (GET /async/projects/{projectId}/output-file/{token}).

Pour bénéficier des atouts du mode authentifié du géocodage de masse, vous devez disposer d’un espace de travail Géoplateforme.

Une fois authentifié, le token Géoplateforme doit être fourni uniquement en header de l’étape 1 du workflow type décrit plus haut. Cela au moyen d’un header Authorization Bearer {mon_token}.

Le reste du workflow s’effectue avec les tokens internes au processus de géocodage de masse asynchrone (voir workflow type ci-dessus).

Pour bénéficier de quotas d’upload augmentés par rapport au mode non authentifié ou de davantage de processus de calcul vous devez :

• Lancer un géocodage de masse asynchrone une première fois en mentionnant le header X-Community associé à l’identifiant Géoplateforme de votre communauté - communauté, pas datastore - au moment de la création du projet de géocodage asynchrone (étape 1 du workflow type). Cela permettra de référencer votre communauté dans le mécanisme de supervision du géocodage asynchrone.
• Contacter le support geoplateforme@ign.fr en décrivant votre projet (volume d’adresse, fréquence du géocodage), type de structure pour laquelle vous opérez afin que nous puissions dimensionner correctement les augmentations de quotas associés à votre espace.