Occitan | Français | English

API et modules

API Basic - Mode d'emploi

Table

# L'URL d'entrée

# Les paramètres obligatoires

# Le paramètre facultatif

# Le format de sortie

# Les erreurs

# Les informations en sortie

# JSON schema

# DTD XML

L'API Basic vous permet de rechercher, à partir d'un mot en français ou en occitan, une entrée du Basic, le dictionnaire du Congrès.

L'URL d'entrée

L'URL de base de l'application est http://api.locongres.org/basic.php. Vous devez y ajouter les paramètres obligatoires et vous pouvez y ajouter un paramètre facultatif. 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 langue : indiquez dans quelle langue vous allez donner le mot à chercher avec le paramètre "lang". Il accepte les valeurs "fr" (pour le français) e "oc" (pour l'occitan).
  • Le mot : indiquez le mot que vous voulez rechercher avec le paramètre "term".

Par exemple, vous pouvez rechercher les traductions en occitan du mot "parler" avec l'URL http://api.locongres.org/basic.php?key=[votre_clé_API]&lang=fr&term=parler. Vous obtenez le résultat suivant :

{
    "query": [
        {
            "id": 0,
            "forms": [
                {
                    "orth": "parler",
                    "PoS": [
                        "V000050000000"
                    ]
                }
            ],
            "trads": [
                {
                    "var": "oc",
                    "orth": "parlar",
                    "PoS": [
                        "V000050000000"
                    ]
                }
            ]
        }
    ]
}

Vous pouvez chercher quelle est la traduction en français du mot "aimable" avec l'URL http://api.locongres.org/basic.php?key=[votre_clé_API]&term=aimable&lang=oc. Vous obtenez le résultat suivant :

{
    "query": [
        {
            "id": 0,
            "forms": [
                {
                    "orth": "affable",
                    "PoS": [
                        "AJ0110",
                        "AJ0210"
                    ]
                }
            ],
            "trads": [
                {
                    "var": "oc",
                    "orth": "aimable",
                    "PoS": [
                        "AJ0110"
                    ],
                    "flexions": [
                        {
                            "var": "oc",
                            "orth": "aimabla",
                            "PoS": [
                                "AJ0210"
                            ]
                        }
                    ]
                },
                {
                    "var": "oc",
                    "orth": "agradiu",
                    "PoS": [
                        "AJ0110"
                    ],
                    "flexions": [
                        {
                            "var": "oc",
                            "orth": "agradiva",
                            "PoS": [
                                "AJ0210"
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "id": 0,
            "forms": [
                {
                    "orth": "aimable",
                    "PoS": [
                        "AJ0110",
                        "AJ0210"
                    ]
                }
            ],
            "trads": [
                {
                    "var": "oc",
                    "orth": "aimable",
                    "PoS": [
                        "AJ0110"
                    ],
                    "flexions": [
                        {
                            "var": "oc",
                            "orth": "aimabla",
                            "PoS": [
                                "AJ0210"
                            ]
                        }
                    ]
                },
                {
                    "var": "oc",
                    "orth": "amist\u00f3s",
                    "PoS": [
                        "AJ0110"
                    ],
                    "flexions": [
                        {
                            "var": "oc",
                            "orth": "amistosa",
                            "PoS": [
                                "AJ0210"
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "id": 0,
            "forms": [
                {
                    "orth": "gentil",
                    "PoS": [
                        "AJ0110"
                    ],
                    "flexions": [
                        {
                            "orth": "gentille",
                            "PoS": [
                                "AJ0210"
                            ]
                        }
                    ]
                }
            ],
            "trads": [
                {
                    "var": "oc",
                    "orth": "brave",
                    "PoS": [
                        "AJ0110"
                    ],
                    "flexions": [
                        {
                            "var": "oc",
                            "orth": "brava",
                            "PoS": [
                                "AJ0210"
                            ]
                        }
                    ]
                },
                {
                    "var": "oc",
                    "orth": "aimable",
                    "PoS": [
                        "AJ0110"
                    ],
                    "flexions": [
                        {
                            "var": "oc",
                            "orth": "aimabla",
                            "PoS": [
                                "AJ0210"
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "id": 0,
            "forms": [
                {
                    "orth": "sympathique",
                    "PoS": [
                        "AJ0110",
                        "AJ0210"
                    ]
                }
            ],
            "trads": [
                {
                    "var": "oc",
                    "orth": "simpatic",
                    "PoS": [
                        "AJ0110"
                    ],
                    "flexions": [
                        {
                            "var": "oc",
                            "orth": "simpatica",
                            "PoS": [
                                "AJ0210"
                            ]
                        }
                    ]
                },
                {
                    "var": "oc",
                    "orth": "aimable",
                    "PoS": [
                        "AJ0110"
                    ],
                    "flexions": [
                        {
                            "var": "oc",
                            "orth": "aimabla",
                            "PoS": [
                                "AJ0210"
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

Le paramètre facultatif

Si vous voulez afficher uniquement les mots occitans dans une variété, ou si vous voulez rechercher un mot en occitan dans une variété particulière, vous pouvez utiliser le paramètre "var" qui prend comme valeurs, pour le moment : "gascon" (formes en occitan gascon), "lengadoc" (formes en occitan languedocien) ou "oc" (forme commune aux deux variétés).

Par exemple, si vous voulez afficher les traductions en occitan gascon du mot français "partir", vous pouvez utiliser l'URL http://api.locongres.org/basic.php?key=[votre_clé_API]&lang=fr&term=partir&var=gascon. Vous obtenez le résultat suivant :

{
    "query": [
        {
            "id": 0,
            "forms": [
                {
                    "orth": "partir",
                    "PoS": [
                        "V000050000000"
                    ]
                }
            ],
            "trads": [
                {
                    "var": "oc",
                    "orth": "partir",
                    "PoS": [
                        "V000050000000"
                    ]
                },
                {
                    "var": "oc",
                    "orth": "anar-se'n",
                    "PoS": [
                        "V000050000000"
                    ]
                }
            ]
        }
    ]
}

Si vous voulez chercher la traduction en français du mot en occitan languedocien "cencha", vous pouvez utiliser l'URL http://api.locongres.org/basic.php?key=[votre_clé_API]&lang=oc&term=cencha&var=lengadoc. Vous obtenez le résultat suivant :

{
    "query": [
        {
            "id": 0,
            "forms": [
                {
                    "orth": "ceinture",
                    "PoS": [
                        "N1210"
                    ]
                }
            ],
            "trads": [
                {
                    "var": "oc",
                    "orth": "cinta",
                    "PoS": [
                        "N1210"
                    ]
                },
                {
                    "var": "oc-lengadoc",
                    "orth": "cencha",
                    "PoS": [
                        "N1210"
                    ]
                }
            ]
        },
        {
            "id": 0,
            "forms": [
                {
                    "orth": "taille",
                    "PoS": [
                        "N1210"
                    ]
                }
            ],
            "trads": [
                {
                    "var": "oc",
                    "orth": "talha",
                    "PoS": [
                        "N1210"
                    ]
                },
                {
                    "var": "oc",
                    "orth": "cinta",
                    "PoS": [
                        "N1210"
                    ]
                },
                {
                    "var": "oc-lengadoc",
                    "orth": "cencha",
                    "PoS": [
                        "N1210"
                    ]
                },
                {
                    "var": "oc",
                    "orth": "talha",
                    "PoS": [
                        "N1210"
                    ]
                },
                {
                    "var": "oc",
                    "orth": "mesura",
                    "PoS": [
                        "N1210"
                    ]
                },
                {
                    "var": "oc-lengadoc",
                    "orth": "pag\u00e8la",
                    "PoS": [
                        "N1210"
                    ]
                }
            ]
        }
    ]
}

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, si vous voulez afficher les traductions du mot français "toujours" au format XML, vous pouvez utiliser l'URL http://api.locongres.org/basic.php?key=[votre_clé_API]&lang=fr&term=toujours&format=xml. Vous obtenez le résultat suivant :

<query>
    <entry id="12787">
        <form>
            <orth>toujours</orth>
            <PoS>AV0000</PoS>
        </form>
        <trad>
            <var>oc-gascon</var>
            <orth>tostemps</orth>
            <PoS>AV0000</PoS>
        </trad>
        <trad>
            <var>oc-lengadoc</var>
            <orth>totjorn</orth>
            <PoS>AV0000</PoS>
        </trad>
    </entry>
</query>

Les erreurs

S'il y a des erreurs dans l'URL ou si la requête ne retourne aucune entrée, 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 : Vous devez indiquer un mot à rechercher
  • 5 : Vous devez indiquer une langue de recherche
  • 6 : Langue incorrecte ("fr" et "oc" acceptés)
  • 7 : Variété incorrecte ("oc", "gascon" et "lengadoc" acceptés)
  • 8 : Nous n'avons trouvé aucune entrée avec vos spécifications

Les informations en sortie

En sortie, vous obtenez une liste d'entrées avec un identifiant unique. Pour chacune sont données :

  • La/les forme(s) en français : avec une orthographe et une ou plusieurs catégories grammaticales
  • La/les traduction(s) en occitan : avec la variété ("oc-gascon" pour l'occitan gascon, "oc-lengadoc" pour l'occitan languedocien, "oc" pour les formes communes aux deux), une orthographe et une ou plusieurs catégories grammaticales

Les catégories grammaticales sont indiquées avec la norme Eagles. Vous trouverez une explication sur comment Lo Congrès utilise la norme Eagles au chapitre 5 de ce 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": {
         \80\BF\80\BF`\FD\B0j\E8\BF\A0\BF@\A0\BF  "items": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "forms": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "orth": {
                                    "type": "string",
                                },
                                "PoS": {
                                    "type": "array",
                                    "items": {
                                        "type":"string"
                                    },
                                    "minItems": 1
                                },
                                "flexions": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "orth": {
                                                "type": "string",
                                            },
                                            "PoS": {
                                                "type": "array",
                                                "items": {
                                                    "type":"string"
                                                },
                                                "minItems": 1
                                            }
                                        },
                                        "required": ["orth", "PoS"]
                                    }
                                }
                            },
                            "required": ["orth", "PoS"]
                        },
                        "minItems": 1
                    },
                    "trads": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "orth": {
                                    "type": "string",
                                },
                                "PoS": {
                                    "type": "array",
                                    "items": {
                                        "type":"string"
                                    },
                                    "minItems": 1
                                },
                                "flexions": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "orth": {
                                                "type": "string",
                                            },
                                            "PoS": {
                                                "type": "array",
                                                "items": {
                                                    "type":"string"
                                                },
                                                "minItems": 1
                                            }
                                        },
                                        "required": ["orth", "PoS"]
                                    }
                                }
                            },
                            "required": ["orth", "PoS"]
                        },
                        "minItems": 1
                    },
                    
                },
                "required": ["id", "forms", "trads"]
            },
            "minItems": 1
        }
    }
}

DTD XML

<! ELEMENT query (entry) >

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

<! ELEMENT entry (form+, trad*) >
<! ATTLIST entry id ID #REQUIRED >

<! ELEMENT form (orth, PoS+) >

<! ELEMENT orth (#PCDATA) >

<! ELEMENT PoS (#PCDATA) >

<! ELEMENT trad (orth, PoS+, var) >

<! ELEMENT var (#PCDATA) >

Hauteur

© Lo Congrès Permanent de la Lenga Occitana, 2017, tous droits réservés - Contacter Lo Congrès