L'API letras pick letters at random, according to their frequency in the language.

Input URL

The application basic URL is http://api.locongres.org/letras.php. You have to add mandatory parameters and you can add facultative parameters. If you don't know how to add parameters in an URL, you can read this tutorial.

Mandatory parameters

You have to add the following parameters :

• Your API key : to use Lo Congrès API, you have to specify a personal API key you can get on the dedicate page. You specify the API key with the "key" parameter.
• The variety : specify the variety from which the letters frequencies must be calculated with the "var" parameter. It allows the values "gascon" (for Gascony occitan), "lengadoc" (for Languedoc occitan) and "provenc" (for Provence occitan).

For instance, if you want to pick letters with a frequency consistent with Provence occitan, you have to use the URL http://api.locongres.org/letras.php?key=[la_vòsta_clau_API]&var=provenc. You get the following result :

Facultative parameters

The number of letters

Specify the number of letters you want with the "nb" parameter. Its value is a number between 1 and 50. If you don't specify this parameter, by default you will have only one letter.

For instance, if you want to draw 15 letters according to their frequency in Languedoc occitan, you have to use the URL http://api.locongres.org/letras.php?key=[la_vòsta_clau_API]&var=lengadoc&nb=15. You get the following result :

Accents

Specify if you want the draw to include accented letters with the "acc" parameter. It allows the values "y" (yes) and "n" (no). If you don't specify this parameter, by default you will get accented characters.

For instance, if you want to draw 5 non-accented letters according to their frequency in Gascony occitan, you have to use the URL http://api.locongres.org/letras.php?key=[la_vòsta_clau_API]&var=gascon&nb=5&acc=n. You get the following result :

Foreign letters

Specify if you want the draw to include foreign letters (k, w, y) with the "foreign" parameter. It allows the values "y" (yes) and "n" (no). If you don't specify this parameter, by default you will not get foreign letters.

For instance, if you want to draw 10 letters according to their frequency in Languedoc occitan, including k, w and y, you have to use the URL http://api.locongres.org/letras.php?key=[la_vòsta_clau_API]&var=lengadoc&nb=10&foreign=o. You get the following result :

Output format

The default output format is JSON. But you can get an XML output in adding "format=xml" to the l'URL.

For instance, if you want to get 12 letters accordingly to their frequency in Provence occitan in XML format, you can use the URL http://api.locongres.org/letras.php?key=[la_vòsta_clau_API]&var=provenc&nb=32&format=xml. You get the following result :

Errors

If there are errors in the input URL or if the query returns no form, the API returns an error with a code and an error text in english. You can see below the error codes with their text :

• 1 : An API key is required
• 2 : Invalid API key
• 3 : Incorrect format ('json' and 'xml' allowed)
• 4 : The number of letters must be between 1 and 50
• 5 : A variety is required
• 6 : Incorrect variety ('gascon', 'lengadoc' and 'provenc' allowed)
• 7 : The values allowed for the "foreign" parameter are "y" and "n"
• 8 : The values allowed for the "acc" parameter are "y" and "n"
• 9 : An error has occured. Please try again.

Output informations

The output you get is a list of letters.

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": "string"
            },
            "minItems": 1,,
            "maxItems": 50
        }
    }
}

DTD XML