API & modules

API fon'Òc - Notice

The fon'Òc API allows you to get an International Phonetic Alphabet transcription of a word or a text.

Input URL

The application basic URL is http://api.locongres.org/fonoc.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.
  • Content to phonetize : specify the word or the text you want to phonetize with the "content" parameter.

For instance, you can phonetize the word "parlar" in every occitan varieties with the URL http://api.locongres.org/fonoc.php?key=[your_APIkey]&content=parlar. You get the following result :

{
    "query": [
        {
            "var":"oc-lengadoc",
            "pronunciation":"/par/'la",
            "richRhyme":"/r/'la",
            "poorRhyme":"/'la",
        {
            "var":"oc-gascon",
            "pronunciation":"/par/'la",
            "richRhyme":"/r/'la",
            "poorRhyme":"/'la",
        {
            "var":"oc-provenc",
            "pronunciation":"/paʀ/'laʀ",
            "richRhyme":"/'laʀ",
            "poorRhyme":"/'aʀ",
        {
            "var":"oc-vivaraup",
            "pronunciation":"/paʀ/'laʀ",
            "richRhyme":"/'laʀ",
            "poorRhyme":"/'aʀ",
        {
            "var":"oc-auvern",
            "pronunciation":"/par/'la",
            "richRhyme":"/r/'la",
            "poorRhyme":"/'la",
        {
            "var":"oc-lemosin",
            "pronunciation":"/par/'la",
            "richRhyme":"/r/'la",
            "poorRhyme":"/'la",
    ]
}

Facultative parameters

Variety

Specify the occitan variety you want to phonetize in the content with the "var" parameter. It allows the values "gascon" (for Gascony occitan), "lemosin" (for Limousin occitan), "lengadoc" (For Languedoc occitan), "provenc" (for Provence occitan), "vivaraup" (for vivaroalpine occitan).

For instance, you can phonetize the word "adiu" in Languedoc occitan with the URL http://api.locongres.org/fonoc.php?key=[your_APIkey]&content=adiu&var=lengadoc. You get the following result :

{
    "query": [
        {
            "var": "oc-lengadoc",
            "pronunciation": "/a/'diw",
            "richRhyme": "/a/'diw",
            "poorRhyme": "/'diw",
        }
    ]
}

Liaisons

Specify with the "link" parameter if you want the words to be separated (link=False) or glued (link=True). If there are liaisons, the final atonic -a, for instance, will disappear if they are followed by a vowel. If you don't specify anything, by default words will be separated.

For instance, you can phonetize the sentence "Lo mon pair que parla occitan." in Gascony occitan, without liaisons, with the URL https://api.locongres.org/fonoc.php?key=[la_vòsta_clau_API]&content=Lo mon pair que parla occitan&var=gascon&link=False. You get the following result :

{
    "query": [
        {
            "var": "oc-gascon",
            "pronunciation": /'lu /'mun /'paj /'ke 'par/lɔ ut/si/'ta",
            "richRhyme": "/i/'ta",
            "poorRhyme": "/'ta",
        }
    ]
}

You can phonetize the same sentence with liaisons using the URL https://api.locongres.org/fonoc.php?key=[la_vòsta_clau_API]&content=Lo mon pair que parla occitan&var=gascon&link=True. You get the following result :

{
    "query": [
        {
            "var": "oc-gascon",
            "pronunciation": /'lu/'mun/'paj/'ke/'par/lut/si/'ta",
            "richRhyme": "/i/'ta",
            "poorRhyme": "/'ta",
        }
    ]
}

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, to display the Gascony occitan phonetizacion of the sentence "Que soi anat dançar" in XML, you can use the URL http://api.locongres.org/fonoc.php?key=[your_APIkey]&content=Que soi anat dançar&var=gascon&link=True&format=xml. You get the something like this :

<query>
    <phon id="1">
        <var>oc-gascon</var>
        <pronunciation>/'ke/'su/ja/'nat/dan/'sa</pronunciation>
        <richRhyme>/n/'sa</richRhyme>
        <poorRhyme>/'sa</poorRhyme>
    </phon>
</query>

Errors

If there are errors in the input URL, 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 content to phonetize is required
  • 5 : A variety is required
  • 6 : Incorrect variety ("auvern", "gascon", "lemosin", "lengadoc", "provenc" and "vivaraup" allowed)
  • 7 : The value of the "link" parameter must be "True" or "False"
  • 8 : An error occured. Please try later or contact our team if the problem remains.

Output informations

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

  • occitan variety of the phonetized content : "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)
  • the phonetized content
  • rich rhyme of the phonetized content
  • poor rhyme of the phonetized content

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": {
                    "var": {
                        "type": "string"
                    },
                    "pronunciation": {
                        "type": "string"
                    },
                    "richRhyme": {
                        "type": "string"
                    },
                    "poorRhyme": {
                        "type": "string"
                    },
                },
                "required": ["var", "pronunciation", "richRhyme", "poorRhyme"]
            },
            "minItems": 1
        }
    }
}

DTD XML

<! ELEMENT query (phon) >

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

<! ELEMENT phon (var, pronunciation, richRhyme, poorRhyme) >

<! ELEMENT var (#PCDATA) >

<! ELEMENT pronunciation (#PCDATA) >

<! ELEMENT richRhyme (#PCDATA) >

<! ELEMENT poorRhyme (#PCDATA) >

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