Occitan | Français | English

API & modules

API punt de lenga - Notice

Contents

# Input URL

# Mandatory parameters

# Display randomly an article

# Output format

# Errors

# Output informations

# JSON schema

# DTD XML

The punt de lenga API allows you to search articles about occitan grammar with a keyword.

Input URL

The application basic URL is http://api.locongres.org/puntlenga.php. 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.
  • Language : you have to specify in which language you will give the keyword with the "lang" parameter. It allows the values "fr" (for french) and "oc" (for occitan).
  • The keyword you want to search : you have to specify the keyword you want to search in articles with the "term" parameter.

For instance, you can search for an article whose french version contains the french keyword "article" with the URL http://api.locongres.org/puntlenga.php?key=[your_APIkey]&term=article&lang=fr&dep=32. You get the following result :

{
    "query": [
        {
            "id": 11,
            "ocTitle": "L'article indefinit",
            "frTitle": "L'article ind\u00e9fini",
            "ocPresentation": "L'article indefinit singular e plural en gascon e en lengadocian.",
            "frPresentation": "L'article ind\u00e9fini singulier et pluriel en gascon et en languedocien.",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9980",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/libe.jpg",
            "cit": "Qu\u2019a escrivut p\u00e8\u00e7as de teatre"
        },
        {
            "id": 12,
            "ocTitle": "L'article partitiu",
            "frTitle": "L'article partitif",
            "ocPresentation": "Ont s'emplega l'article partitiu \u00ab de \u00bb, ont s'exprim\u00eds lo partitiu pel substantiu sol ?",
            "frPresentation": "O\u00f9 emploie-t-on l'article partitif \u00ab de \u00bb, o\u00f9 exprime-t-on le partitif par le substantif seul ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9981",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/versar.jpg",
            "cit": "Balha-li d'aiga"
        },
        {
            "id": 32,
            "ocTitle": "Los noms de montanhas",
            "frTitle": "Les noms de montagnes",
            "ocPresentation": "Quan cau utilizar un article abans un nom de montanha ?",
            "frPresentation": "Quand faut-il utiliser un article avant un nom de montagne ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/10001",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/montanha.jpg",
            "cit": "Deis Aups ai Piren\u00e8us"
        },
        {
            "id": 39,
            "ocTitle": "Noms de pa\u00efses e de rius",
            "frTitle": "Noms de pays et de rivi\u00e8res",
            "ocPresentation": "Quand emplegar l'article abans un nom de pa\u00eds o de riu ?",
            "frPresentation": "Quand employer l'article avant un nom de pays ou de rivi\u00e8re ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/10008",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/riu.jpg",
            "cit": "Qu\u2019es pres de Tarn"
        }
    ]
}

You can search for an article whose occitan version contains the occitan keyword "auxiliar" with the URL http://api.locongres.org/puntlenga.php?key=[your_APIkey]&lang=oc&term=auxiliar. You get the following result :

{
    "query": [
        {
            "id": 2,
            "ocTitle": "Causir l\u2019auxiliar \u2013 cases especifics",
            "frTitle": "Choisir l'auxilliaire - cas sp\u00e9cifiques",
            "ocPresentation": "Los cases especific d'emplec dels auxiliars \u00ab \u00e8sser \u00bb e \u00ab aver \u00bb",
            "frPresentation": "Les cas sp\u00e9cifiques d'emploi des auxilliaires \u00ab \u00e8sser \u00bb et \u00ab avoir \u00bb",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9971",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/galerian.jpg",
            "cit": "Qu\u2019av\u00e8van tribalhat com galerians"
        },
        {
            "id": 3,
            "ocTitle": "Causir l\u2019auxiliar \u2013 principis generals",
            "frTitle": "Choisir l'auxilliaire - principes g\u00e9n\u00e9raux",
            "ocPresentation": "Quand emplegar l'auxiliar \u00ab aver \u00bb, quand emplegar l'auxiliar \u00ab \u00e8sser \u00bb ?",
            "frPresentation": "Quand employer l'auxilliaire \u00ab aver \u00bb, quand employer l'auxilliaire \u00ab \u00eatre \u00bb ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9972",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/tribunal.jpg",
            "cit": "L\u2019acusat qu\u2019\u00e8ra estat aquitat"
        },
        {
            "id": 36,
            "ocTitle": "Los v\u00e8rbes semi-auxiliars 1",
            "frTitle": "Les verbes semi-auxilliaires 1",
            "ocPresentation": "Quales son los v\u00e8rbes semi-auxiliars e coma los emplegar ?",
            "frPresentation": "Quels sont les verbes semi-auxilliaires et comment les employer ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/10005",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/veitura.jpg",
            "cit": "Ven de crompar una veitura"
        },
        {
            "id": 46,
            "ocTitle": "Los v\u00e8rbes semi-auxiliars 2",
            "frTitle": "Les verbes semi-auxilliaires 2",
            "ocPresentation": "A de qu\u00e9 servisson los v\u00e8rbes semi-auxiliars ?",
            "frPresentation": "\u00c0 quoi servent les verbes semi-auxilliaires ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/10015",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/cant.jpg",
            "cit": "Comenc\u00e8t de cantar"
        }
    ]
}

Display randomly an article

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

{
    "query": [
        {
            "id": 3,
            "ocTitle": "Causir l\u2019auxiliar \u2013 principis generals",
            "frTitle": "Choisir l'auxilliaire - principes g\u00e9n\u00e9raux",
            "ocPresentation": "Quand emplegar l'auxiliar \u00ab aver \u00bb, quand emplegar l'auxiliar \u00ab \u00e8sser \u00bb ?",
            "frPresentation": "Quand employer l'auxilliaire \u00ab aver \u00bb, quand employer l'auxilliaire \u00ab \u00eatre \u00bb ?",
            "url": "http:\/\/www.locongres.org\/fr\/applications\/expressoc-expressions-fr\/expressoc-navigation-par-fiches\/9972",
            "picture": "http:\/\/www.locongres.org\/images\/expressions\/tribunal.jpg",
            "cit": "L\u2019acusat qu\u2019\u00e8ra estat aquitat"
        }
    ]
}

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

<query>
    <article id="20">
        <ocTitle>La tonicitat</ocTitle>
        <frTitle>La tonicité</frTitle>
        <ocPresentation>Quaus mots son tonics, atònes proclitics o atònes enclitics ?</ocPresentation>
        <frPresentation>Quels mots sont toniques, atones proclitiques ou atones enclitiques ?</frPresentation>
        <url>http://www.locongres.org/fr/applications/expressoc-expressions-fr/expressoc-navigation-par-fiches/9989</url>
        <picture>http://www.locongres.org/images/expressions/aniversari.jpg</picture>
        <citation>Lo present qu’ei sus la taula</citation>
    </article>
</query>

Errors

If there are errors in the input URL or if the query returns no article, 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 article
  • 6 : Incorrect language ('oc' and 'fr' allowed)
  • 7 : No article found with your conditions

Output informations

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

  • Its occitan title
  • Its french title
  • Its occitan presentation
  • Its french presentation
  • The URL of the full article on Lo Congrès website
  • The citation illustrating the article
  • The URL of the picture which illustrates the citation
  • *The author you have to credit if you use this picture

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

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"
                    },
                    "ocTitle": {
                        "type": "string"
                    },
                    "frTitle": {
                        "type": "string"
                    },
                    "ocPresentation": {
                        "type": "string"
                    },
                    "frPresentation": {
                        "type": "string"
                    },
                    "url": {
                        "type": "string"
                    },
                    "picture": {
                        "type": "string"
                    },
                    "pictureCredit": {
                        "type": "string"
                    },
                    "cit": {
                        "type": "string"
                    },
                },
                "required": ["id", "ocTitle", "frTitle", "ocPresentation", "frPresentation", "url", "picture", "cit"]
            },
            "minItems": 1
        }
    }
}

DTD XML

<! ELEMENT query (article) >

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

<! ELEMENT article (citation, frPresentation, frTitle, ocPresentation, ocTitle, picture, pictureCredit?, url) >
<! ATTLIST article id ID #REQUIRED >

<! ELEMENT citation (#PCDATA) >

<! ELEMENT frPresentation (#PCDATA) >

<! ELEMENT frTitle (#PCDATA) >

<! ELEMENT ocPresentation (#PCDATA) >

<! ELEMENT ocTitle (#PCDATA) >

<! ELEMENT picture (#PCDATA) >

<! ELEMENT pictureCredit (#PCDATA) >

<! ELEMENT url (#PCDATA) >

Height

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