API Flyerz
API Flyerz
API Flyerz
API Flyerz
Commencez avec l'API Flyerz
Propulsé par GitBook

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

  1. 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 !

  2. 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...

  3. 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 en paramètre POST ou GET suivant la route, le champ appId avec pour valeur votre identifiant d'application et le champ secretKey avec pour valeur la clé d'API.

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
required
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
required
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
required
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
required
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
required
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
required
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
required
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 1 month ago
Sommaire
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)
3. Routes de l'API
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
4. Gérer les erreurs