L'API express'Òc vous permet d'afficher des expressions en occitan avec leur traduction française à partir d'un mot-clé.

L'URL d'entrée

L'URL de base de l'application est http://api.locongres.org/expressoc.php. Vous devez y ajouter les paramètres obligatoires et vous pouvez y ajouter un paramètre facultatif. Si vous ne savez pas ajouter des paramètres à un URL, nous vous renvoyons à ce tutoriel.

Les paramètres obligatoires

Il vous faut obligatoirement indiquer les paramètres suivants :

• Votre clé API : pour utiliser les API du Congrès, il vous faut indiquer une clé API personnelle que nous pouvons vous fournir sur la page dédiée. Vous l'indiquez avec le paramètre "key".
• La langue : indiquez dans quelle langue vous allez donner le mot que vous voulez trouver dans l'expression ou sa traduction avec le paramètre "lang". Il accepte les valeurs "fr" (pour le français) e "oc" (pour l'occitan).
• Le mot à chercher : indiquez le mot que vous voulez trouver dans l'expression occitane (ou dans sa traduction française) avec le paramètre "term".

Par exemple, vous pouvez chercher des expressions en occitan qui contiennent le mot "boca" avec l'URL http://api.locongres.org/expressoc.php?key=[votre_clé_API]&term=boca&lang=oc. Vous obtenez le résultat suivant :

Vous pouvez aussi chercher des expressions dont la traduction contient "fuir" avec l'URL http://api.locongres.org/expressoc.php?key=[votre_clé_API]&term=fuir&lang=fr. Vous obtenez le résultat suivant :

Les paramètres facultatifs

La variété

Vous pouvez choisir d'afficher des expressions uniquement dans une variété de l'occitan en utilisant le paramètre "var". Pour le moment, il accepte les valeurs "gascon" (pour l'occitan gascon), "lemosin" (pour l'occitan limousin), "provenc" (pour l'occitan provençal) et "lengadoc" (pour l'occitan languedocien).

Par exemple, si vous voulez afficher toutes les expressions en occitan languedocien qui contiennent le mot "ivèrn", vous pouvez utiliser l'URL http://api.locongres.org/expressoc.php?key=[votre_clé_API]&term=ivèrn&lang=oc&var=lengadoc. Vous obtenez le résultat suivant :

Si vous voulez afficher une expression au hasard en occitan gascon, vous pouvez utiliser l'URL http://api.locongres.org/expressoc.php?key=[votre_clé_API]&term=random&var=gascon. Vous obtenez quelque chose comme :

La présence d'illustrations

Vous pouvez choisir de n'afficher que les expressions qui sont illustrées par une image et un son en utilisant le paramètre "ill" avec la valeur "true".

Par exemple, pour afficher toutes les expressions illustrées qui contiennent le mot "talent", vous pouvez utiliser l'URL http://api.locongres.org/expressoc.php?key=[la_vòsta_clau_API]&term=talent&lang=oc&ill=true. Vous obtenez quelque chose comme :

Afficher une expression au hasard

Vous pouvez afficher une expression au hasard en indiquant la valeur "random" pour le paramètre "term". Dans ce cas-là, vous n'êtes pas obligés d'ajouter le paramètre de langue. L'URL http://api.locongres.org/expressoc.php?key=[votre_clé_API]&term=random vous permet donc d'afficher une expression au hasard. Vous obtenez quelque chose comme :

Le format de sortie

Par défaut, le format de sortie est JSON. Mais vous pouvez obtenir une sortie au format XML en ajoutant "format=xml" à l'URL.

Par exemple, si vous voulez afficher une expression au hasard au format XML, vous pouvez utiliser l'URL http://api.locongres.org/expressoc.php?key=[votre_clé_API]&term=random&format=xml. Vous obtenez quelque chose comme :

Les erreurs

S'il y a des erreurs dans l'URL ou si la requête ne retourne aucune expression, l'API retourne une erreur avec un code et un texte d'erreur en anglais. Vous trouverez ci-dessous, pour chaque code d'erreur, la traduction de son texte en français :

• 1 : Vous devez indiquer une clé API
• 2 : Clé API invalide
• 3 : Format incorrect ("json" et "xml" acceptés)
• 4 : Vous devez indiquer un terme
• 5 : Vous devez indiquer une langue de recherche si vous n'êtes pas en train d'afficher une expression au hasard
• 6 : Langue incorrecte ("fr" et "oc" acceptés)
• 7 : Variété incorrecte ("gascon", "lemosin", "provenc" et "lengadoc" acceptés)
• 8 : Nous n'avons trouvé aucun toponyme avec vos spécifications
• 9 : Le paramètre "ill" n'accepte que les valeurs "true" et "false"

Les informations en sortie

En sortie, vous obtenez une liste d'expressions avec un identifiant unique. Pour chacune sont donnés :

• L'expression en occitan
• Sa traduction en français
• *L'URL de l'image qui illustre l'expression
• *L'auteur qu'il faut créditer si on utilise cette image
• *L'URL de l'enregistrement audio de l'expression
• *L'URL de l'article complet sur le site du Congrès
• La variété dans laquelle est l'expression : "oc-gascon" (occitan gascon), "oc-lemosin" (occitan limousin), "oc-provenc" (occitan provençal) ou "oc-lengadoc" (occitan languedocien)

Les champs précédés de * n'apparaissent pas obligatoirement.

JSON schema

{
    "type": "object",
    "properties": {
        "error": {
            "type": "object",
            "properties": {
                "code": {
                    "description": "The unique identifier for an error",
                    "type": "integer"
                },
                "text": {
                    "description": "A description of the error",
                    "type": "string"
                }
            },
            "required": ["code", "text"]
        },
        "query": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "oc": {
                        "type": "string"
                    },
                    "var": {
                        "type": "string"
                    },
                    "fr": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string"
                    },
                    "picture": {
                        "type": "string"
                    },
                    "pictureCredit": {
                        "type": "string"
                    },
                    "sound": {
                        "type": "string"
                    },
                },
                "required": ["id", "oc", "var", "fr", "url"]
            },
            "minItems": 1
        }
    }
}

DTD XML