API & modules

API express'Òc - Notice

The express'Òc API allows you to display occitan expressions with their french translations from a keyword.

Input URL

The application basic URL is http://api.locongres.org/expressoc.php. You have to add mandatory parameters and you can add a facultative parameter. 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.
  • Language : you have to specify in which language you will give the word you want to find in the expression or its translation with the "lang" parameter. It allows the values "fr" (for french) and "oc" (for occitan).
  • Term to find : specify the term you want to find in the occitan expression (or in its translation) with the "term" parameter.

For instance, you can find occitan expressions which contains the term "boca" with the URL http://api.locongres.org/expressoc.php?key=[your_APIkey]&term=boca&lang=oc. You get the following result :

{
    "query": [
        {
            "id": 37,
            "oc": "Aver la boca devath lo nas",
            "var": "oc-gascon",
            "fr": "\u00catre comme tout le monde",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/369",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/nas.jpg",
            "pictureCredit": "David Shankbone",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/bocanas.mp3"
        },
        {
            "id": 220,
            "oc": "Parlar dab la boca ub\u00e8rta ",
            "var": "oc-gascon",
            "fr": "Dire des na\u00efvet\u00e9s",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9705",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/pots.jpg",
            "pictureCredit": "Hamed Saber",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/10Parlardablabocauberta.mp3"
        }
    ]
}

You cal also search expressions whose french translation contains "fuir" with the URL http://api.locongres.org/expressoc.php?key=[your_APIkey]&term=fuir&lang=fr. You get the following result :

{
    "query": [
        {
            "id": 86,
            "oc": "Gratar camin",
            "var": "oc-lengadoc",
            "fr": "Aller rapidement, d\u00e9taler, fuir",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/419",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/camin.jpg",
            "pictureCredit": "Manu_H",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/gratarcamin.mp3"
        }
    ]
}

The facultative parameters

The variety

You can choose to display an expression only in one occitan variety with the "var" parameter. For the moment, it allows the values "gascon" (for Gascony occitan), "lemosin" (for Limousin occitan), "provenc" (for Provence occitan) and "lengadoc" (for Languedoc occitan).

For instance, if you want to display all Languedoc occitan expressions which contains the word "ivèrn", you can use the URL http://api.locongres.org/expressoc.php?key=[your_APIkey]&term=ivèrn&lang=oc&var=lengadoc. You get the following result :

{
    "query": [
        {
            "id": 230,
            "oc": "Al gr\u00f2s de l\u2019iv\u00e8rn",
            "var": "oc-lengadoc",
            "fr": "Dans le fort de l\u2019hiver",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9715",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/neu.jpg",
            "pictureCredit": "Twice25",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/grosivern.mp3"
        }
    ]
}

If you want to display randomly a Gascony occitan expression, you can use the URL http://api.locongres.org/expressoc.php?key=[your_APIkey]&term=random&var=gascon. You get the something like this :

{
    "query": [
        {
            "id": 128,
            "oc": "Qu'a vist a passar la l\u00e8be",
            "var": "oc-gascon",
            "fr": "Il a eu une d\u00e9convenue",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9558",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/lebe.jpg",
            "pictureCredit": "Fmickan",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/vistpassarlebe.mp3"
        }
    ]
}

Illustrations presence

You can choose to display only expressions that are illustrated by a picture and a sound using the "ill" parameter with the value "true".

For instance, to display all the illustrated expressions that contain the word "talent", you can use the URL http://api.locongres.org/expressoc.php?key=[la_vòsta_clau_API]&term=talent&lang=oc&ill=true. You get the following result :

{
    "query": [
        {
            "id": 70,
            "oc": "Ai un talent que lo vesi córrer",
            "var": "oc-lengadoc",
            "fr": "J’ai une faim de loup",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/403",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/correr.jpg",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/talentcorrer.mp3"
        }
    ]
}

Display randomly an expression

You can display randomly an expression in specifying the value "random" for the "term" parameter. In that case, you don't have to specify the language parameter. So the URL http://api.locongres.org/expressoc.php?key=[your_APIkey]&term=random allows you to display randomly an expression. You get the something like this :

{
    "query": [
        {
            "id": 276,
            "oc": "Destampar l\u2019aiga",
            "var": "oc-lengadoc",
            "fr": "Tirer la chasse",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9761",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/chasseau.jpg",
            "pictureCredit": "Cold Steel",
            "sound": "http:\/\/www.locongres.org\/images\/audio\/expressions\/destamparaiga.mp3"
        }
    ]
}

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 display randomly an expression in XML, you can use the URL http://api.locongres.org/expressoc.php?key=[your_APIkey]&term=random&format=xml. You get the something like this :

<query>
    <expr id="131">
        <oc>Metre un tap a la flaüta</oc>
        <var>oc-lengadoc</var>
        <fr>Se taire, la fermer</fr>
        <url>http://www.locongres.org/fr/applications/expressoc-expressions-fr/expressoc-navigation-par-fiches/9561</url>
        <picture>http://www.locongres.org/images/expressions/flauta.jpg</picture>
        <pictureCredit>Propi</pictureCredit>
        <sound>http://www.locongres.org/images/audio/expressions/tapflauta.mp3</sound>
    </expr>
</query>

Errors

If there are errors in the input URL or if the query returns no expressions, 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 : A term is required
  • 5 : A language is required if you don't ask for a random expression
  • 6 : Incorrect language ('oc' and 'fr' allowed)
  • 7 : Incorrect variety ('gascon', 'lemosin', 'provenc' and 'lengadoc' allowed)
  • 8 : No expression found with your conditions
  • 9 : The 'ill' parameter only accepts the values 'true' and 'false'

Output informations

The output you get is a list of expressions with an unique ID. For each one, you get :

  • The occitan expression
  • Its french translation
  • *The URL of the picture which illustrates the expression
  • *The author you have to credit if you use this picture
  • *The URL of the expression audio recording
  • *The URL of the full article on Lo Congrès website
  • The occitan variety of the expression : "oc-gascon" (Gascony occitan), "oc-lemosin" (Limousin occitan), "oc-provenc" (Provence occitan) or "oc-lengadoc" (Languedoc occitan)

The fields with an * don't appear for each expression.

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

<! ELEMENT query (expr) >

<! ELEMENT error (#PCDATA) >
<! ATTLIST error code ID #REQUIRED >

<! ELEMENT expr (fr, oc, picture?, pictureCredit?, sound?, url, var) >
<! ATTLIST expr id ID #REQUIRED >

<! ELEMENT fr (#PCDATA) >

<! ELEMENT oc (#PCDATA) >

<! ELEMENT picture (#PCDATA) >

<! ELEMENT pictureCredit (#PCDATA) >

<! ELEMENT sound (#PCDATA) >

<! ELEMENT url (#PCDATA) >

<! ELEMENT var (#PCDATA) >

© Lo Congrès Permanent de la Lenga Occitana, 2017, all rights reserved - Contact Lo Congrès