PositionStack apparaît plutôt dans des intégrations légères, souvent une simple classe de service qui encapsule un appel d'API au sein d'une application plus vaste. Ce type d'intégration est assez petit pour être facile à oublier et juste assez gros pour être pénible à réécrire. Notre hôte compatible vise à supprimer entièrement cette réécriture.
L'hôte reproduit à l'identique les paramètres de requête et le corps de réponse de PositionStack, à l'exception des textes de copyright, de conditions et de confidentialité, qui sont les nôtres et non ceux du fournisseur d'origine. Une requête construite pour l'endpoint de géocodage de PositionStack peut être envoyée sans modification à notre hôte, et la réponse revient avec la structure que le code existant analyse déjà.
Ce qui change, c'est un nom d'hôte et une clé. Cette clé s'authentifie avec celle de nos quatre méthodes standard qu'utilise déjà votre intégration : un en-tête X-API-Key, un en-tête Authorization: Bearer, l'authentification HTTP Basic avec la clé comme nom d'utilisateur, ou un paramètre de requête.
Une simple classe de service qui encapsule un appel est aussi le genre d'intégration pour laquelle personne ne tient de documentation, si bien que les questions arrivent souvent sous forme de tickets d'assistance de la part de celui qui a hérité du code plus tard. L'équipe d'assistance de My Geocode dispose de réponses types pour ces questions de compatibilité récurrentes, la signification des en-têtes, les formats de clé, ce qui change et ce qui ne change pas, afin qu'une question de migration simple obtienne une réponse rapide au lieu d'attendre derrière des demandes plus complexes.
Tester la structure d'une réponse avant de toucher au code est tout aussi simple : la démo interactive sur /demo/ peut envoyer un exemple de requête à n'importe quel endpoint ou hôte compatible et afficher les champs exacts renvoyés, ce qui suffit souvent à confirmer qu'un appel au format PositionStack sera correctement analysé en aval.
Les tarifs ne varient pas selon l'hôte compatible qui a traité une requête. Toute adresse bénéficie de 2 500 requêtes gratuites par jour sans aucune clé, comptées par réseau. Une clé ajoute ses propres 2 500 requêtes gratuites par jour supplémentaires. Au-delà de ces deux quotas, le crédit prépayé coûte 0,0001 € la requête, ou un forfait Unlimited couvre l'utilisation pour 50 € par mois, exactement comme pour tous les autres endpoints et hôtes de la plateforme.
Chaque réponse comporte également nos en-têtes de quota : X-Quota-Limit, X-Quota-Used, X-Quota-Free-Remaining, X-Quota-Network-Used, X-Credits-Remaining, X-Key-IPs-Used, X-Key-IPs-Limit et X-Quota-Reset, offrant une visibilité sur l'utilisation qu'une intégration PositionStack classique n'exposerait pas autrement.
Pour tout ce qui dépasse les champs standard de la réponse compatible, mg_extras=1 dans la requête, ou un en-tête X-MG-Extras, ajoute des extras facultatifs par-dessus, entièrement sur activation et désactivés par défaut.
L'hôte est documenté sur /compatibility/positionstack/, et une présentation plus large du fonctionnement des dix-sept hôtes compatibles se trouve sur /docs/compatibility/. Si PositionStack est niché dans un service quelque part dans votre stack, le rediriger ici est un changement modeste et réversible à tester.