Woosmap Search API : rechercher et filtrer vos points de vente

L’équipe Woosmap met à disposition la Search API, pensée pour aider vos utilisateurs à localiser précisément le ou les points de vente qui les intéressent. Depuis un client web ou un service back-end, vous interrogez vos emplacements via des requêtes** RESTful afin d’effectuer des recherches spatiales et attributaires simples et performantes. Les résultats sont renvoyés au format standard GeoJSON** pour faciliter leur intégration. Cas d’usage courants : retrouver les emplacements à proximité d’une adresse géocodée ou filtrer une liste de points de vente selon leurs équipements.

Comment l’utiliser

Le point d’entrée REST /search est entièrement décrit dans la documentation développeur. Pour construire votre première recherche, partez d’une requête comme celle ci-dessous (elle renvoie l’ensemble de vos données, paginées). Remplacez le paramètre {public_key} par la clé de votre projet.

À noter : toutes les requêtes API doivent être émises depuis un Referrer autorisé pour la clé du projet (www.mysite.com dans cet exemple). Avec cURL, le referrer se définit via l’option -H, --header <header>. Pour le moment, l’ajout d’un nouveau nom de domaine se fait sur demande auprès de nos équipes. Côté back-end, utilisez votre** private_key plutôt que la public_key**, cette dernière étant réservée au développement côté client.

Deux familles de querystrings sont disponibles pour interroger l’API :

Paramètre de requête : il s’appuie sur les attributs des emplacements via &query=, en précisant le champ, l’opérateur et la valeur souhaités. Vous pouvez filtrer par Types, Tags, User Attributes, identifiant ou nom de point de vente, ou par une combinaison de ces critères. La rubrique Fields détaille les exemples et les opérateurs pris en charge pour chaque champ.

Paramètres géographiques : autour d’un point géographique avec &lat= et &lng= (récupérables via notre Geolocation API ou un service de géocodage) et un paramètre radius, ou le long d’une polyligne via encoded_polyline.

Exemple de recherche avec filtre

Voici un exemple qui combine, avec la Woosmap Search API, une recherche autour d’une position géographique et un filtre sur le type de point de vente. Le point de vente le plus proche (Coffee Shop) n’est renvoyé que s’il se situe dans un rayon de 250 km (&max_distance=250000) autour de la position de l’utilisateur (obtenue via la méthode getUserPosition() de la Recommendation API) ou d’une adresse géocodée (via Google Geocoding API).

Dans cet exemple, nous appelons la Recommendation API et getUserPosition() à l’ouverture de la page. Si l’utilisateur est déjà identifié par Woosmap, un Coffee Shop est renvoyé. Sinon, vous pouvez géocoder une adresse pour obtenir un résultat. N’hésitez pas à jouer avec la case à cocher « Take Away Coffee » et le champ numérique du nombre de coffee shops à récupérer pour affiner les résultats. Un aperçu de l’URL d’appel de l’API REST est également affiché.

Pour toute question sur le contenu ou la démarche décrite, contactez-nous via la page contact.

Liens utiles

• Documentation de la Woosmap Data API pour interroger vos emplacements.
• Récupérer la position de l’utilisateur à l’ouverture de la page avec la Geolocation API.