La requête API HTTP

La requête API HTTP doit respecter le schéma suivant:

unemployaid.com/api/{API name}/{API version}/{GET parameters}

Avec plusieurs valeurs possibles:

Paramètres communs

  • API name: smatching
  • API dernière version: d04
  • GET parameters:
    • codeapiaccess: Obligatoire, il s'agit du code d'accès à l'API qui vous a été fourni lors de votre inscription.
    • format: json par défaut, vous pouvez indiquer xml pour un retour au format XML.

Paramètres spécifiques à certains appels (cf. exemples)

Demander la liste de mes questionnaires

  • GET parameters:
    • rlist: Obligatoire Alimentée avec qs: La liste à retourner contient les questionnaires.
    • target: Si cette donnée n'est pas valorisée, nous vous retournons la liste intégrale de vos questionnaires. Si elle est alimentée, nous vous retournons uniquement les questionnaires à destination de la population indiquée: 0 pour les personnes, 1 pour les entreprises ou organismes.
    • qslabel: Facultatif. Si cette valeur est renseignée, nous retournerons uniquement les questionnaires dont le libellé contient cette chaîne.
  • Données obtenues:
    Vous obtiendrez en retour un tableau (format JSON ou XML) comportant une ligne par questionnaire trouvé, alimentée avec les données suivantes:
    • total_displayed: Nombre total d'occurences trouvées.
    • id_questionnaire: identifiant du questionnaire, à transmettre dans la variable qs selon le besoin des prochains appels.
    • qslabel: Libellé du questionnaire.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • qsdescription: Description du questionnaire.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • target: Population cible du questionnaire: 0 pour des personnes, 1 pour des entreprises.
  • Messages d'erreur:
    • result: valorisé à 'no result' si aucune donnée n'a été trouvée.

Exemple:

json
https://www.unemployaid.com/api/smatching/d04/?codeapiaccess={INSERT YOUR CODE}&rlist=qs&target=0
xml
https://www.unemployaid.com/api/smatching/d04/?format=xml&codeapiaccess={INSERT YOUR CODE}&rlist=qs&target=0

Obtenir la première question d'un questionnaire

  • GET parameters:
    • qs: Obligatoire Identifie de manière unique un questionnaire
    • uid: Identifiant d'un de vos utilisateurs. Cette valeur est à votre discrétion. Elle permettra d'identifier de manière unique un utilisateur dans vos appels. Si cette valeur est renseignée, nous vérifions si l'utilisateur a déjà commencé à répondre à ce questionnaire et reprenons là où il en était. Lors de cet appel, cette donnée est facultative, dans le suivant, elle sera obligatoire (afin d'enregistrer ses réponses).
  • Données obtenues:
    Vous obtiendrez en retour un tableau (format JSON ou XML) comportant une ligne par réponse possible alimentée avec les données suivantes:
    • total_displayed: Nombre total d'occurences couples question/réponse trouvées.
    • id_question: identifiant de la question.
    • qnlabel: Libellé de la question.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • qndescription: Description de la question.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • id_response: identifiant de la réponse.
    • rslabel: Libellé de la réponse.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • rsdescription: Description de la réponse.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.

Exemple:

json
https://www.unemployaid.com/api/smatching/d04/?codeapiaccess={INSERT YOUR CODE}&qs=243
xml
https://www.unemployaid.com/api/smatching/d04/?format=xml&codeapiaccess={INSERT YOUR CODE}&qs=243

Obtenir la question suivante

  • GET parameters:
    • rs: Obligatoire Identifie de manière unique la dernière réponse fournie.
    • uid: Obligatoire Identifiant d'un de vos utilisateurs. Cette valeur est à votre discrétion. Elle permet d'identifier de manière unique un utilisateur dans vos appels. Cette information permet de rattacher les réponses à cet utilisateur.
  • Données obtenues:
    Vous obtiendrez en retour un tableau (format JSON ou XML) comportant une ligne par réponse possible alimentée avec les données suivantes:
    • total_displayed: Nombre total d'occurences couples question/réponse trouvées.
    • id_question: identifiant de la question.
    • qnlabel: Libellé de la question.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • qndescription: Description de la question.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • id_response: identifiant de la réponse.
    • rslabel: Libellé de la réponse.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • rsdescription: Description de la réponse.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
  • Message de fin:
    • result: valorisé à 'end' indique que vous avez atteint la dernière question du questionnaire.
  • Messages d'erreur:
    • result: valorisé à 'uid missing. Please add this information to the get datas of the link.' indique que uid, qui est obligatoire, n'a pas été correcteent indiqué.

Exemple:

json
https://www.unemployaid.com/api/smatching/d04/?codeapiaccess={INSERT YOUR CODE}&rs=23&uid=Az5g670
xml
https://www.unemployaid.com/api/smatching/d04/?format=xml&codeapiaccess={INSERT YOUR CODE}&rs=23&uid=Az5g670

Obtenir le profil d'un utilisateur

  • GET parameters:
    • rlist: Obligatoire Valorisé avec profile.
    • qs: Obligatoire Identifie le questionnaire auquel l'utilisateur a répondu.
    • uid: Obligatoire Identifiant d'un de vos utilisateurs. Cette valeur est à votre discrétion. Elle permet d'identifier de manière unique un utilisateur dans vos appels. Cette information permet de rattacher les réponses à cet utilisateur.
  • Données obtenues:
    Vous obtiendrez en retour un tableau (format JSON ou XML) comportant une ligne par réponse possible alimentée avec les données suivantes:
    • total_displayed: Nombre total d'occurences de carcatéristiques trouvées pour ce uid et ce qs.
    • id_profile: identifiant du profil.
    • id_questionnaire: identifiant du questionnaire.
    • uid: identifiant de l'utilisateur.
    • label: Libellé du profil tel que décliné pour cette cible (personne ou entreprise).
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • description: Description du profil telle que déclinée pour cette cible (personne ou entreprise).
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • ponderation: Nombre de points de pondération accumulés pour ce profil ou cette caractéristique.
    • nb_responses: Nombre de réponses ayant servi à calculer cette pondération. Permet de calculer une moyenne.
  • Messages d'erreur:
    • result: valorisé à 'Missing: [['uid.'], ['qs'], ['prf']]' indique les variables manquantes de votre appel.

Exemple:

json
https://www.unemployaid.com/api/smatching/d04/?codeapiaccess={INSERT YOUR CODE}&rlist=profile&qs=223&uid=Az5g670
xml
https://www.unemployaid.com/api/smatching/d04/?format=xml&codeapiaccess={INSERT YOUR CODE}&rlist=profile&qs=223&uid=Az5g670

Supprimer une caractéristique d'un profil utilisateur

Vous pouvez effacer un résultat ou plusieurs résultats de tests pour un utilisateur. Pour celà, vous devez nous envoyer une requête par caractéristique à effacer. Vous connaîtrez les identifiants grâce à l'appel décrit ci-dessus.
  • GET parameters:
    • rlist: Obligatoire Valorisé avec del.
    • prf: Obligatoire Identifie le profil ou la caractéristique à effacer.
    • qs: Obligatoire Identifie le questionnaire auquel l'utilisateur a répondu.
    • uid: Obligatoire Identifiant d'un de vos utilisateurs. Cette valeur est à votre discrétion. Elle permet d'identifier de manière unique un utilisateur dans vos appels. Cette information permet de rattacher les réponses à cet utilisateur.
  • Message retour:
    • result: valorisé à 'Profile ['prf'] for user ['uid'] on questionnaire 'qs': DELETED.' indique que a suppression a bien été réalisée.
  • Messages d'erreur:
    • result: valorisé à 'Error: You are not allowed to delete this information.'

Exemple:

json
https://www.unemployaid.com/api/smatching/d04/?codeapiaccess={INSERT YOUR CODE}&rlist=del&prf=12&qs=223&uid=Az5g670
xml
https://www.unemployaid.com/api/smatching/d04/?format=xml&codeapiaccess={INSERT YOUR CODE}&rlist=del&prf=12&qs=223&uid=Az5g670

Obtenir la liste des personnes ou entreprises correspondant, "matchant"

Cet appel vous restitue une liste d'identifiants uid (ceux que vous nous avez transmis lors du déroulement de vos questionnaires) dont les résultats aux questionnaires sont compatibles ou en corrélation.
Pour identifier la liste des uid compatibles avec l'uid cité en référence, nous comparons leurs résultats aux tests.
Nous calculons tout d'abord le score moyen de l'uid de référence caractéristique par caractéristique.
Nous collectons ensuite la liste des uid disposant d'au moins une caractéristique compatible à 75% minimum (par défaut. Vous pouvez indiquer un autre ratio) avec une caractéristique de l'uid de référence.
Nous calculons ce ratio de compatibilité pour chaque caractéristique, plus un taux de compatibilité global.
Ces informations vous permettront de connaître le niveau de compatibilité de chaque uid, caractéristique par caractéristique. A votre charge ensuite de présenter les résultats et les informations de votre choix à vos utilisateurs, dont nous ne connaissons que luid et les résultats aux tests.
  • GET parameters:
    • rlist: Obligatoire Valorisé avec matching.
    • uid: Obligatoire Identifiant d'un de vos utilisateurs. Cette valeur est à votre discrétion. Elle permet d'identifier de manière unique un utilisateur dans vos appels. Cette information permet de rattacher les résultats à cet utilisateur.
    • qs: Obligatoire Identifie le questionnaire dans le contexte duquel vous voulez faire le rapprochement.
    • ratio: Entier entre 0 et 100 définissant le taux de compatibilité minimum à une caractéristique pour figurer dans la liste du résultat.
    • target: Si cette donnée n'est pas valorisée, nous vous retournons la liste des uid compatibles dont le type (personne ou entreprise) est différent de celui donné en référence.
      Si l'uid fournit en paramètre est une personne, nous ferons par défaut un rapprochement avec les uid appartenant à des entreprises.
      Si elle est alimentée, nous vous retournons uniquement les questionnaires à destination de la population indiquée: 0 pour les personnes, 1 pour les entreprises ou organismes, même si cette valeur est la même que celle de l'uid de référence.
    • limit: Permet de choisir le nombre maximum de résultats. Si vous n'indiquez rien dans ce paramètre, nous limiterons par défaut à 20 uid en retour.
  • Données obtenues:
    Vous obtiendrez en retour un tableau (format JSON ou XML) comportant une ligne par réponse possible alimentée avec les données suivantes:
    • total: Nombre total de points de pondération obtenus.
    • uid: identifiant de la personne ou l'entreprise sélectionnée.
    • profiles: Tableau détaillant le résultat caractéristique par caractéristique.
      Ce tableau est composé ainsi:
      • id_profile: identifiant du profil.
      • score: Note moyenne entre -5 et +5, obtenue dans ce profil.
      • compatibility: Taux de compatibilité calculé pour ce profil. ((score de référence * score comparé / score de référence au carré) * 100).
      • ref_score: Score de référence, obtenu par l'uid passé en paramètre sur cette caractéristique. Note moyenne entre -5 et +5, obtenue dans ce profil.
      • max: Valeur de référence globale= somme des carrés des pondérations moyennes obtenues par l'uid passé en paramètre dans toutes ses caractéristiques pour le questionnaire choisi. Permet de calculer le taux de compatibilité global (qui peut être supérieur à 100%)
    • glob_compat: Taux de compatibilité global calculé sur la totalité des caractéristiques du profil. Permet de classer les résultats de façon transversale.
  • Messages d'erreur:
    • result: valorisé à 'Ratio parameter must be an integer between 0 and 100.' Le ratio passé en paramètre doit être un entier entre 0 et 100.
    • result: valorisé à 'UID parameter is mandatory.' indique que l'uid est manquant.
    • result: valorisé à 'The UID indicated is not known by our service.' indique que l'uid est invalide.
    • result: valorisé à 'The qs parameter is mandatory.' indique que la variable qs, obligatoire, est manquante.

Exemple:

json
https://www.unemployaid.com/api/smatching/d04/?codeapiaccess={INSERT YOUR CODE}&rlist=matching&qs=223&uid=Az5g670&ratio=76&limit=240
xml
https://www.unemployaid.com/api/smatching/d04/?format=xml&codeapiaccess={INSERT YOUR CODE}&rlist=matching&qs=223&uid=Az5g670&ratio=76&limit=240

Obtenir la description d'un profil ou d'une caractéristique

En retour d'un appel smatching, vous obtenez une liste d'uid, d'id_profile avec leurs scores et un score global. L'identifiant de profil ou de caractéristique (id_profile) vous permettra de remonter la description complète du profil afin de l'afficher selon vos besoins via l'appel suivant:
  • GET parameters:
    • rlist: Obligatoire Valorisé avec profile.
    • prf: Obligatoire Identifie le profil ou la caractéristique à remonter.
  • Données obtenues:
    Vous obtiendrez en retour un tableau (format JSON ou XML) comportant une ligne par réponse possible alimentée avec les données suivantes:
    • id_profile: identifiant du profil.
    • label0: Libellé du profil tel que décliné pour la cible 'personnes'.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • label1: Libellé du profil tel que décliné pour la cible 'entreprises'.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • description0: Description du profil telle que déclinée pour la cible 'personnes'.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
    • description1: Description du profil telle que déclinée pour la cible 'entreprises'.
      Attention: les données textuelles sont encodées par htmlentites et peuvent nécessiter l'utilisation de la fonction html_entity_decode pour l'affichage.
  • Messages d'erreur:
    • result: valorisé à 'Missing: [['uid.'], ['qs'], ['prf']]' indique les variables manquantes de votre appel.

Exemple:

json
https://www.unemployaid.com/api/smatching/d04/?codeapiaccess={INSERT YOUR CODE}&rlist=profile&prf=25
xml
https://www.unemployaid.com/api/smatching/d04/?format=xml&codeapiaccess={INSERT YOUR CODE}&rlist=profile&prf=25

Comparer les profils de deux uid

Cet appel vous permet de connaître le taux de compatibilité entre deux uid dans le contexte d'un questionnaire donné.
  • GET parameters:
    • rlist: Obligatoire Valorisé avec compare.
    • qs: Obligatoire Identifie le questionnaire dont les caractéristiques seront évaluées.
    • uid: Obligatoire Comporte l'uid de référence et l'uid à comparer, séparés par une virgule.
  • Données obtenues:
    Vous obtiendrez en retour un tableau (format JSON ou XML) comportant une ligne par réponse possible alimentée avec les données suivantes:
    • ref_uid: uid de référence.
    • comp_uid: uid comparé.
    • ref_max: Le score de référence.
    • profiles: Le tableau des profils comparés composé de:
      • id_profile: L'identifiant du profil ou de la caractéristique.
      • ref_score: Le score moyen obtenu par l'uid de référence à cette caractéristique.
      • score: Le score moyen obtenu par l'uid comparé à cette caractéristique.
      • compatibility: Le ratio de compatibilité caculé pour ce profil ou caractéristique. Valorisé à 'NA' s'il ne peut être appliqué (pour une moyenne de référence de 5 sur 10, on considère que la caractéristique n'est pas représentative)
    • comp_score: Le score global de l'uid comparé.
    • compatibility: Le taux de compatiblité global calculé.
  • Messages d'erreur:
    • result: 'The qs parameter is mandatory' Le paramètre qs est obligatoire, il doit correspondre à un de vos questionnaires au moins.
    • result: 'UID parameter is mandatory.' L'un des uid est manquant.
    • result: 'The UID XYZ is not known by our service.' L'un des uid que vous avez indiqués n'existe pas.

Exemple:

json
https://www.unemployaid.com/api/smatching/d04/?codeapiaccess={INSERT YOUR CODE}&rlist=compare&uid=FBU8N1U9U,0rBaQA6Iz&qs=20
xml
https://www.unemployaid.com/api/smatching/d04/?format=xml&codeapiaccess={INSERT YOUR CODE}&rlist=compare&uid=FBU8N1U9U,0rBaQA6Iz&qs=20

Nous contacter Conditions générales d'utilisation

©Hervé Schilling