Commencez avec l'API Flyerz

L'API Flyerz permet de récupérer tous les évènements disponibles sur la plateforme Flyerz.
1. Récupérer ses clés d'API
Vous disposez d'un identifiant d'application et de deux clés d'API : une clé de développement (pour vos tests) et une clé de production (destinée à l'utilisation finale).
Pour demander vos clés, contactez-nous à l'adresse communication (arobase) flyerz (point) fr en nous expliquant votre besoin.
Vos clés d'API sont privées, conservez-les en lieu sûr.
2. Commençons
Fonctionnement de l'API Flyerz
Flyerz récupère pour le compte de ses clients le contenu évènementiel disponible sur internet sur la zone géographique voulue par les clients : concerts, expos, afterworks, évènements sportifs, petits ou grands... bref tout !
Le contenu est filtré, trié dans le but d'avoir le contenu le plus qualitatif possible : tous les évènements ont une photo, un titre, une description, un lieu, une adresse, des coordonnées géographiques etc...
Les évènements sont régulièrement mis à jour ou supprimés quand ils le sont dans leur base de données originelle.
Le contenu est par conséquent dynamique, l'API est donc destinée à un usage à la volée. Si vous désirez sauvegarder dans votre base de données les évènements Flyerz, vous pouvez souscrire à l'offre Export en nous contactant.
L'API dispose de nombreux outils pour récupérer les évènements que vous trouverez ci-dessous.
Point de terminaison (endpoint)
La route principale de l'API est https://api.flyerz.fr/v2/.
Toutes les routes renvoient une réponse au format JSON.
Utilisation de la clé d'API
Vous pouvez utiliser l'API en passant dans l'en-tête de la requête (le header) la clé Authorization ayant pour valeur Bearer XYZ (remplacez XIZ par la clé d'API). C'est la méthode recommandée.
Autre possibilité, vous pouvez utiliser l'API en passant en paramètre POST ou GET suivant la route, le champ secretKey avec pour valeur la clé d'API.
Dans les deux cas, vous devez également passer en paramètre POST ou GET suivant la route, le champ appId avec pour valeur l'identifiant de votre application.
Important : les recommandations d'usage (trucs et astuces)
Les suggestions d'évènements avec l'IA de Flyerz
L'API dispose d'une route events/suggestions pour recommander des évènements de manière personnalisée à l'utilisateur. L'Intelligence Artificielle se base sur ses consultations antérieures. Ainsi il convient de passer à chacune des routes de l'API dans le champ sourceUserId un ID que vous aurez généré de votre côté qui permet à Flyerz d'identifier les requêtes qui proviennent d'un même device.
Cet identifiant ne doit pas pas être une donnée personnelle pour respecter l'anonymat de vos utilisateurs et pour respecter le RGPD sans avoir à demander aux utilisateurs d'accepter le partage de leurs données personnelles. Il peut s'agir par exemple de l'ID du device.
Les mises en avant
Vous avez la possibilité via notre back office de mettre en avant des évènements dans l'API. Ces évènements apparaîtront par exemple dans les premiers résultats de la recherche par exemple. 
Pour les identifier, l'évènement a un champ isHighlighted avec la valeur true. Si vous voyez ce champ et cette valeur sur un évènement, il est recommandé de changer l'affichage visuel de l'évènement pour qu'il ressorte plus par rapport aux autres évènements.
Voici un exemple ci-dessous, où l'évènement mis en avant à gauche ressort plus que l'évènement à droite :
3. Routes de l'API
get
Rechercher des évènements
https://api.flyerz.fr/v2/search
C'est LA route principale de l'API. Vous pouvez faire des recherches simples ou complexes en croisant vos paramètres, par exemple : rechercher "concert" à proximité d'un point géographique, récupérer les évènements d'une sélection etc...
Request
Response
Request
Query Parameters
rows
optional
integer
Nombre d'éléments renvoyés (par défaut : 10, maximum : 1000)
appId
required
string
Identifiant d'application
secretKey
optional
string
Clé de l'API
platform
required
string
"web"|"android"|"ios"
sourceUserId
optional
string
ID anonyme de l'utilisateur/du device
language
optional
string
Langue, ex : "fr"
q
optional
string
Recherche textuelle
start
optional
string
Date de début (format : YYYY-MM-DD H:i:s, timezone : Europe/Paris)
end
optional
string
Date de fin (mêmes format et timezone)
selections
optional
string
IDs des sélections (ex : "100|46|53")
location
optional
string
Coordonnée géographique (ex : "46.75,6.598"), doit être utilisé avec le champ "radius"
radius
optional
integer
Rayon exprimé en mètres (valeur max : 10000), doit être utilisé avec le champ "location"
offset
optional
integer
Position du 1er élément renvoyé par l'API (commence par défaut à 0)
Response
200: OK
{
    "success": true,
    "events": [
        {
            "id": 123456,
            "name": "Swing quartet en concert",
            "pictureURL": "https://...",
            "type": {
                "name: "Concert",
                "color: "#FE3065"
            },
            "startDate": "2022-08-31 20:00:00",
            "endDate": "2022-08-31 22:00:00",
            "description": "Blablabla...",
            "phone": null, (facultatif)
            "website": null, (facultatif)
            "fee": "P", (F : gratuit, P : payant) (facultatif)
            "price": "12 €", (facultatif)
            "ticketURL": null, (lien de billetterie) (facultatif)
            "place": {
                "name": "Arena de Genève",
                "pictureURL": null, (facultatif)
                "description": null, (facultatif)
                "address": "Route de l'Aéroport 29, 1218 Le Grand-Saconnex",
                "city": "Le Grand-Saconnex",
                "phone": null, (facultatif)
                "website": null, (facultatif)
                "latitude": 46.233581,
                "longitude": 6.112322
            },
            "isHighlighted": false,
            "creationDate": "2020-02-18 12:37:59",
            "lastUpdate": "2020-02-19 15:25:48",
            "canceled": false (facultatif)
        }
    ]
}
get
Évènement
https://api.flyerz.fr/v2/events/{id}
La route renvoie les informations d'un évènement dans le champ event.

Elle renvoie aussi dans le champ highlightedEvents des évènements mis en avant par vos clients ou partenaires. Il est recommandé de les afficher sur la page afin de leur donner de la visibilité.

Le champ similarEvents renvoie des évènements du même type (des concerts si l'évènement recherché est un concert) qui peuvent être suggérés à l'utilisateur.
Request
Response
Request
Path Parameters
id
optional
integer
ID de l'évènement
Query Parameters
appId
required
string
Identifiant d'application
secretKey
optional
string
Clé d'API
platform
required
string
"web"|"android"|"ios"
sourceUserId
optional
string
ID anonyme de l'utilisateur/du device
language
optional
string
Langue, ex : "fr"
Response
200: OK
{
    "success": true,
    "event": {
        "id": 123456,
        "name": "Swing quartet en concert",
        "pictureURL": "https://...",
        "type": {
            "name: "Concert",
            "color: "#FE3065"
        },
        "startDate": "2022-08-31 20:00:00",
        "endDate": "2022-08-31 22:00:00",
        "description": "Blablabla...",
        "phone": null, (facultatif)
        "website": null, (facultatif)
        "fee": "P", (F : gratuit, P : payant) (facultatif)
        "price": "12 €", (facultatif)
        "ticketURL": null, (lien de billetterie) (facultatif)
        "place": {
            "name": "Arena de Genève",
            "pictureURL": null, (facultatif)
            "description": null, (facultatif)
            "address": "Route de l'Aéroport 29, 1218 Le Grand-Saconnex",
            "city": "Le Grand-Saconnex",
            "phone": null, (facultatif)
            "website": null, (facultatif)
            "latitude": 46.233581,
            "longitude": 6.112322
        },
        "isHighlighted": false,
        "creationDate": "2020-02-18 12:37:59",
        "lastUpdate": "2020-02-19 15:25:48",
        "canceled": false (facultatif)
    },
    "highlightedEvents": [],
    "similarEvents": []
}
get
Suggestions d'évènements
https://api.flyerz.fr/v2/events/suggestions
Évènements recommandés à un utilisateur par l'IA de Flyerz.
Request
Response
Request
Query Parameters
appId
required
string
Identifiant d'application
secretKey
optional
string
Clé d'API
platform
required
string
"web"|"android"|"ios"
sourceUserId
required
string
​
language
optional
string
Langue, ex : "fr"
Response
200: OK
{
    "success": true,
    "events": [
        {
            "id": 123456,
            "name": "Swing quartet en concert",
            "pictureURL": "https://...",
            "type": {
                "name: "Concert",
                "color: "#FE3065"
            },
            "startDate": "2022-08-31 20:00:00",
            "endDate": "2022-08-31 22:00:00",
            "description": "Blablabla...",
            "phone": null, (facultatif)
            "website": null, (facultatif)
            "fee": "P", (F : gratuit, P : payant) (facultatif)
            "price": "12 €", (facultatif)
            "ticketURL": null, (lien de billetterie) (facultatif)
            "place": {
                "name": "Arena de Genève",
                "pictureURL": null, (facultatif)
                "description": null, (facultatif)
                "address": "Route de l'Aéroport 29, 1218 Le Grand-Saconnex",
                "city": "Le Grand-Saconnex",
                "phone": null, (facultatif)
                "website": null, (facultatif)
                "latitude": 46.233581,
                "longitude": 6.112322
            },
            "isHighlighted": false,
            "creationDate": "2020-02-18 12:37:59",
            "lastUpdate": "2020-02-19 15:25:48",
            "canceled": false (facultatif)
        }
    ]
}
post
Consultation d'un évènement
https://api.flyerz/fr/v2/events/{id}/show
Cette route doit être appelée pour signaler à l'API que l'utilisateur consulte la page d'un évènement.

Cette route alimente les statistiques d'utilisation dans le back office et entraîne l'IA pour recommander à l'utilisateur des évènements qu'il est susceptible d'aimer.
Request
Response
Request
Path Parameters
id
required
integer
ID de l'évènement
Query Parameters
appId
required
string
Identifiant d'application
secretKey
optional
string
Clé d'API
platform
required
string
"web"|"android"|"ios"
sourceUserId
required
string
ID anonyme de l'utilisateur/du device
language
optional
string
Langue, ex : "fr"
Response
200: OK
{
    "success": true
}
post
Ajout/retrait d'un évènement en "favori"
https://api.flyerz.fr/v2/events/{id}/favorite
Sur certaines plateformes, l'utilisateur peut vouloir sauvegarder/ajouter en favori un évènement sur le support client (site internet, appli mobile). Cette route doit être appelée quand un utilisateur ajoute en favori un évènement (champ "action" = "add") ou quand il le retire de ses favoris (champ "action" = "delete").

Cette route entraîne l'IA pour recommander à l'utilisateur des évènements qu'il est susceptible d'aimer.
Request
Response
Request
Path Parameters
id
optional
integer
ID de l'évènement
Query Parameters
appId
required
string
ID d'application
secretKey
optional
string
Clé d'API
platform
required
string
"web"|"android"|"ios"
sourceUserId
required
string
ID anonyme de l'utilisateur/du device
action
required
string
"add"/"delete"
language
optional
string
Langue, ex : "fr"
Response
200: OK
{
    "success": true
}
get
Liste des sélections
https://api.flyerz.fr/v2/selections
Vous pouvez récupérer une liste de sélections (qu'on peut aussi appeler filtres), par exemple : "Ateliers", "Concerts", "Nature / plein air", etc...
Cette liste peut être affichée pour simplifier pour les utilisateurs la recherche d'évènements.

Cette liste est dynamique, elle est définie avec vous suivant vos souhaits. Elle est entièrement personnalisable, il est possible par exemple d'avoir une sélection "Nouvel an" qui apparaît dans la liste 15 jours avant le 31 décembre et qui regroupe toutes les fêtes prévues à Bordeaux à cette date. Une liste de sélections standards est déjà définie.
Request
Response
Request
Query Parameters
appId
required
string
Identifiant d'application
secretKey
optional
string
Clé d'API
platform
required
string
"web"|"android"|"ios"
sourceUserId
required
string
ID anonyme de l'utilisateur/du device
language
optional
string
Langue, ex : "fr"
Response
200: OK
{
    "success": true,
    "selections": [
        {
            "id": 56,
            "name": "Spectacle",
            "description": null, (facultatif)
            "pictureURL": null (facultatif)
        }
    ]
}
get
Exporter des évènements
https://api.flyerz/fr/v2/exports/{id}
Cette route est réservée aux clients qui ont souscrit à l'offre Export pour sauvegarder les évènements dans leur base de données.

Pour vous permettre de tenir à jour votre base de données d'évènements, la route renvoie les évènements qui ont été ajoutés, mis à jour ou supprimés depuis la dernière fois que vous avez appelé cette route.
Un évènement modifié ou supprimé (le champ "deleted" apparaît) dans l'API Flyerz doit être actualisé en conséquence dans votre base.
Request
Response
Request
Path Parameters
id
required
integer
ID du projet d'export
Query Parameters
appId
required
string
ID d'application
secretKey
optional
string
Clé d'API
platform
required
string
"web"|"android"|"ios"
lastUpdate
optional
string
Permet de ne renvoyer que les évènements ajoutés, modifiés, supprimés depuis cette date (format : YYYY-MM-DD H:i:s, timezone : Europe/Paris). Si ce champ n'est pas rempli, la route renvoie tous les évènements non supprimés dont la date de fin est supérieure à la date d'exécution de la requête.
offset
optional
integer
Position du 1er élément renvoyé par l'API (comment par défaut à 0)
rows
optional
integer
Nombre d'éléments renvoyés (par défaut : 10, maximum : 1000)
language
optional
string
Langue, ex : "fr"
Response
200: OK
{
    "success": true,
    "events": [
        {
            "id": 123456,
            "name": "Swing quartet en concert",
            "pictureURL": "https://...",
            "type": {
                "name: "Concert",
                "color: "#FE3065"
            },
            "startDate": "2022-08-31 20:00:00",
            "endDate": "2022-08-31 22:00:00",
            "description": "Blablabla...",
            "phone": null, (facultatif)
            "website": null, (facultatif)
            "fee": "P", (F : gratuit, P : payant) (facultatif)
            "price": "12 €", (facultatif)
            "ticketURL": null, (lien de billetterie) (facultatif)
            "place": {
                "name": "Arena de Genève",
                "pictureURL": null, (facultatif)
                "description": null, (facultatif)
                "address": "Route de l'Aéroport 29, 1218 Le Grand-Saconnex",
                "city": "Le Grand-Saconnex",
                "phone": null, (facultatif)
                "website": null, (facultatif)
                "latitude": 46.233581,
                "longitude": 6.112322
            },
            "isHighlighted": false,
            "creationDate": "2020-02-18 12:37:59",
            "lastUpdate": "2020-02-19 15:25:48",
            "canceled": false, (facultatif)
            "deleted": false (facultatif)
        }
    ]
}
4. Gérer les erreurs
L'API renvoie une erreurs si la requête n'est pas valide (ressource demandée inexistante, clé d'API incorrecte...).
Voici le format des erreurs renvoyées par l'API :
{
    "success": false,
    "error": {
        "type": "unknownAppId",
        "message": "The app ID does not exist."
    }
}
Dernière mise à jour 6 months ago
Commencez avec l'API Flyerz

1. Récupérer ses clés d'API

2. Commençons

Fonctionnement de l'API Flyerz

Point de terminaison (endpoint)

Utilisation de la clé d'API

Important : les recommandations d'usage (trucs et astuces)

Les suggestions d'évènements avec l'IA de Flyerz

Les mises en avant

3. Routes de l'API

getRechercher des évènements

getÉvènement

getSuggestions d'évènements

postConsultation d'un évènement

postAjout/retrait d'un évènement en "favori"

getListe des sélections

getExporter des évènements

4. Gérer les erreurs

get
Rechercher des évènements

get
Évènement

get
Suggestions d'évènements

post
Consultation d'un évènement

post
Ajout/retrait d'un évènement en "favori"

get
Liste des sélections

get
Exporter des évènements
