L'API letras tire des lettres au hasard en respectant leur fréquence dans la langue.

L'URL d'entrée

L'URL de base de l'application est http://api.locongres.org/letras.php. Vous devez y ajouter les paramètres obligatoires et vous pouvez y ajouter des paramètres facultatifs. 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 variété : indiquez la variété à partir de laquelle il faut calculer la fréquence des lettres avec le paramètre "var". Il accepte les valeurs "gascon" (pour l'occitan gascon), "lengadoc" (pour l'occitan languedocien) et "provenc" (pour l'occitan provençal).

Par exemple, pour tirer des lettres avec une fréquence cohérente avec l'occitan provençal, vous pouvez utiliser l'URL http://api.locongres.org/letras.php?key=[la_vòsta_clau_API]&var=provenc. Vous obtenez le résultat suivant :

Les paramètres facultatifs

Le nombre de lettres

Indiquez le nombre de lettres que vous voulez avec le paramètre "nb". Il prend pour valeur un nombre entre 1 et 50. Si vous ne reseignez pas ce paramètre, par défaut, vous n'aurez qu'une lettre.

Par exemple, si vous voulez tirer 15 lettres en accord avec leur fréquence en occitan languedocien, vous pouvez utiliser l'URL http://api.locongres.org/letras.php?key=[la_vòsta_clau_API]&var=lengadoc&nb=15. Vous obtenez le résultat suivant :

Les accents

Indiquez si le tirage doit inclure des lettres accentuées avec le paramètre "acc". Il accepte les valeurs "y" (oui) et "n" (non). Si vous ne reseignez pas ce paramètre, par défaut, vous aurez des lettres accentuées.

Par exemple, si vous voulez tirer 5 lettres non accentuées en accord avec leur fréquence en occitan gascon, vous pouvez utiliser l'URL http://api.locongres.org/letras.php?key=[la_vòsta_clau_API]&var=gascon&nb=5&acc=n. Vous obtenez le résultat suivant :

Les lettres étrangères

Indiquez si le tirage doit inclure des lettres étrangères (k, w, y) avec le paramètre "foreign". Il accepte les valeurs "y" (oui) et "n" (non). Si vous ne reseignez pas ce paramètre, par défaut, vous n'aurez aucune lettre étrangère.

Par exemple, si vous voulez tirer 10 lettres en accord avec leur fréquence en occitan languedocien, comprenant les lettres k, w et y, vous pouvez utiliser l'URL http://api.locongres.org/letras.php?key=[la_vòsta_clau_API]&var=lengadoc&nb=10&foreign=o. Vous obtenez le résultat suivant :

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, pour obtenir 12 lettres en accord avec leur fréquence en occitan provençal au format XML, vous pouvez utiliser l'URL http://api.locongres.org/letras.php?key=[la_vòsta_clau_API]&var=provenc&nb=32&format=xml. Vous obtenez le résultat suivant

Les erreurs

S'il y a des erreurs dans l'URL ou si la requête ne retourne aucune forme, 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 : Le nombre de lettres doit être compris entre 1 et 50
• 5 : Vous devez indiquer une variété
• 6 : Variété incorrecte ("gascon", "lengadoc" et "provenc" acceptés)
• 7 : Les valeurs acceptées pour le paramètre "foreign" sont "y" et "n"
• 8 : Les valeurs acceptées pour le paramètre "acc" sont "y" et "n"
• 9 : Une erreur est apparue. Veuillez rééssayer

Les informations en sortie

En sortie, vous obtenez une liste de lettres.

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": {
                    "word": {
                        "type": "string"
                    },
                    "join": {
                        "type": "string"
                    },
                },
                "required": ["word", "join"]
            }
        }
    }
}

DTD XML