Occitan | Français | English

API & modules

API sinonimes - Notice

Contents

# Input URL

# Mandatory parameters

# The facultative parameter

# Output format

# Errors

# Output informations

# JSON schema

# DTD XML

The sinonimes API allows you to get synonyms of an occitan word.

Input URL

The application basic URL is http://api.locongres.org/synonyms. You have to add mandatory 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.
  • Word : you have to specify the word of which you want to search synonyms with the "term" parameter.

For instance, if you want to search synonyms for "polit" in all occitan varieties, you can use the URL http://api.locongres.org/synonyms.php?key=[your_APIkey]&term=polit. You get the following result :

{
    "query": [
        {
            "id": "18601",
            "orth": "alindat",
            "PoS": "AJ0110",
            "var": "oc-gascon",
        },
        {
            "id": "46788",
            "orth": "aunèste",
            "PoS": "AJ0110",
            "var": "oc-gascon",
        },
        {
            "id": "62313",
            "orth": "bèl",
            "PoS": "AJ0110",
            "var": "oc-lengadoc",
        },
        {
            "id": "62769",
            "orth": "belòi",
            "PoS": "AJ0110",
            "var": "oc-lengadoc",
        },
        {
            "id": "64375",
            "orth": "beroget",
            "PoS": "AJ0110",
            "var": "oc-gascon",
        },
        {
            "id": "64410",
            "orth": "berogin",
            "PoS": "AJ0110",
            "var": "oc-gascon",
        },
        {
            "id": "64451",
            "orth": "beròi",
            "PoS": "AJ0110",
            "var": "oc-gascon",
        },
        {
            "id": "64507",
            "orth": "berojon",
            "PoS": "AJ0110",
            "var": "oc-gascon",
        },
        {
            "id": "65567",
            "orth": "bèth",
            "PoS": "AJ0110",
            "var": "oc-gascon",
        },
        {
            "id": "66579",
            "orth": "bien aprés",
            "PoS": "AJ0110",
            "var": "oc-auvern",
        },
        {
            "id": "66585",
            "orth": "bien graciós",
            "PoS": "AJ0110",
            "var": "oc-auvern",
        },
        {
            "id": "66594",
            "orth": "bien oneste",
            "PoS": "AJ0110",
            "var": "oc-auvern",
        },
        {
            "id": "72698",
            "orth": "bon",
            "PoS": "AJ0110",
            "var": "oc-lengadoc",
        },
        {
            "id": "73805",
            "orth": "borgau",
            "PoS": "AJ0110",
            "var": "oc-vivaraup",
        },
        {
            "id": "78666",
            "orth": "brave",
            "PoS": "AJ0110",
            "var": "oc-lemosin",
        },
        {
            "id": "78667",
            "orth": "brave",
            "PoS": "AJ0110",
            "var": "oc-vivaraup",
        },
        {
            "id": "81103",
            "orth": "bròi",
            "PoS": "AJ0110",
            "var": "oc-gascon",
        },
        {
            "id": "82623",
            "orth": "brunit",
            "PoS": "AJ0110",
            "var": "oc-lengadoc",
        },
        {
            "id": "124778",
            "orth": "corós",
            "PoS": "AJ0110",
            "var": "oc-vivaraup",
        },
        {
            "id": "126008",
            "orth": "cortés",
            "PoS": "AJ0110",
            "var": "oc-gascon",
        },
        {
            "id": "128150",
            "orth": "crane",
            "PoS": "AJ0110",
            "var": "oc-lemosin",
        },
        {
            "id": "242928",
            "orth": "gente",
            "PoS": "AJ0110",
            "var": "oc-lemosin",
        },
        {
            "id": "274888",
            "orth": "jòli",
            "PoS": "AJ0110",
            "var": "oc-vivaraup",
        },
        {
            "id": "286261",
            "orth": "lis",
            "PoS": "AJ0110",
            "var": "oc-gascon",
        },
        {
            "id": "286511",
            "orth": "lisse",
            "PoS": "AJ0110",
            "var": "oc-auvern",
        },
        {
            "id": "329984",
            "orth": "oneste",
            "PoS": "AJ0110",
            "var": "oc-vivaraup",
        },
        {
            "id": "363741",
            "orth": "plan",
            "PoS": "AJ0110",
            "var": "oc-auvern",
        },
        {
            "id": "364713",
            "orth": "plasent",
            "PoS": "AJ0110",
            "var": "oc-gascon",
        },
        {
            "id": "368056",
            "orth": "polidet",
            "PoS": "AJ0110",
            "var": "oc-gascon",
        }
    ]
}

The facultative parameter

You can specify in which occitan variety you want to search synonyms with the "var" parameter. For the moment, its allows the values "auvern" (for Auvergne occitan), "gascon" (for Gascony occitan), "lemosin" (for Limousin occitan), "lengadoc" (for Languedoc occitan), "provenc" (for Provence occitan) and "vivaraup" (for vivaroalpine occitan).

For instance, if you want to search synonyms for "parlar" in vivaroalpine occitan, you can use the URL http://api.locongres.org/synonyms.php?key=[your_APIkey]&var=vivaraup&term=parlar. You get the following result :

{
    "query": [
        {
            "id": 261194,
            "orth": "charrar",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 263297,
            "orth": "devisar",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 269011,
            "orth": "calcular",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 270720,
            "orth": "causar",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 270732,
            "orth": "provocar",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 276412,
            "orth": "contestar",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 276427,
            "orth": "discutir",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 276903,
            "orth": "conversar",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 276913,
            "orth": "dialogar",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 283986,
            "orth": "dialecte",
            "PoS": "N1110"
            "var": "oc-vivaraup"
        },
        {
            "id": 284562,
            "orth": "barjar",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 284570,
            "orth": "discutar",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 284579,
            "orth": "chicotear",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 284587,
            "orth": "chapitrolhar",
            "PoS": "V000050000000"
            "var": "oc-vivaraup"
        },
        {
            "id": 309207,
            "orth": "lengatge",
            "PoS": "N1110"
        }
    ]
}

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 Provence occitan synonyms for "estatjant" in XML format, you can use the URL http://api.locongres.org/synonyms.php?key=[your_APIkey]&var=provenc&term=estatjant&format=xml. You get the following result :

<query>
    <syn id="245462">
        <orth>abitant</orth>
        <PoS>N1110</PoS>
        <var>oc-provenc</var>
    </syn>
</query>

Errors

If there are errors in the input URL or if the query returns no synonym, 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 variety is required
  • 6 : Incorrect variety ('auvern', 'lemosin', 'lengadoc', 'gascon', 'provenc', 'vivaraup' allowed)
  • 7 : No synonym found with your conditions

Output informations

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

  • Its spelling
  • Its grammatical category
  • Its occitan variety : "oc-auvern" (Auvergne occitan), "oc-gascon" (Gascony occitan), "oc-lemosin" (Limousin occitan), "oc-lengadoc" (Languedoc occitan), "oc-provenc" (Provence occitan) and "oc-vivaraup" (vivaroalpine occitan)

Grammatical categories are given with Eagles norm. You will find an explanation about the way Lo Congrès use Eagles norm in the fifth chapter of this document.

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"
                    },
                    "orth": {
                        "type": "string"
                    },
                    "PoS": {
                        "type": "string"
                    },
                    "var": {
                        "type": "string"
                    },
                },
                "required": ["id", "orth", "PoS", "var"]
            },
            "minItems": 1
        }
    }
}

DTD XML

<! ELEMENT query (syn) >

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

<! ELEMENT orth (#PCDATA) >

<! ELEMENT PoS (#PCDATA) >

<! ELEMENT syn (orth, PoS, var) >
<! ATTLIST syn id ID #REQUIRED >

<! ELEMENT var (#PCDATA) >

Height

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