> For the complete documentation index, see [llms.txt](https://api-docs.speechace.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.speechace.com/api-reference/score-word.md).

# Score Word

{% hint style="info" %}
**Run In Postman:** [Score a Word](https://docs.speechace.com/#824b2e5a-4e68-4946-ab15-7c5bdf0e7084)
{% endhint %}

The Score Word API is optimal for scoring pronunciation of a single word. It supports scoring optimizations and model combinations targeted on utterances where the speaker is pronouncing a single word.

\
A word can be a dictionary word, a custom word (aka non-word, non-sense word) defined with markup, a Multiple Choice (MC) combination where each target is a single word.

### Request Format 

The endpoint to use will depend on the [region](/getting-started/pre-requisites/api-regions-and-endpoints.md) of your subscription. For example, for US West, the endpoint is <https://api.speechace.co>.

<mark style="color:$success;">`POST`</mark> [`https://api.speechace.co/api/scoring/word/v9/json`](https://api.speechace.co/api/scoring/writing/v9/json)

### Headers

<table><thead><tr><th width="252.4296875">Name</th><th>Value</th></tr></thead><tbody><tr><td>Content-Type</td><td><code>application/json</code></td></tr></tbody></table>

### Query Parameters

<table><thead><tr><th width="136">Parameter</th><th width="117">Type</th><th>Description</th></tr></thead><tbody><tr><td>key</td><td>String</td><td><p><strong>Required</strong></p><p><em>API</em> <a href="/pages/FY5QJQ5NVDkUtPtG080s"><em>key</em></a> <em>issued by Speechace.</em></p></td></tr><tr><td>dialect</td><td>String</td><td><p><strong>Optional</strong> <em>default = <code>en-us</code></em> </p><p><em>Supported values are: <code>en-us</code>, <code>en-gb</code>, <code>es-es</code>, <code>es-mx</code>, <code>fr-fr</code>, <code>fr-ca</code></em></p></td></tr><tr><td>user_id</td><td>String</td><td><p><strong>Optional</strong></p><p><em>A unique anonymized identifier (generated by your applications) for the end-user who submitted the response.</em></p></td></tr></tbody></table>

### Request Body

<table><thead><tr><th width="175.2265625">Parameter</th><th width="117">Type</th><th>Description</th></tr></thead><tbody><tr><td>word</td><td>String</td><td><p><strong>Required.</strong> Max length: 300 characters.</p><p><em>Word to score. Can be expressed as one of:</em></p><ul><li><em>text: (e.g. "cat")</em></li><li><em>arpa_mark: (e.g. "[cat]{k ah1 t}")</em></li><li><em>Multiple Choice with '\n' as separator: (e.g. "cat\ndog")</em></li><li><em>Multiple choice with arpa_mark: (e.g. "[cat]{k ah1 t}\n[dog]{d ao1 g})</em><br></li></ul><p><em><strong>Note:</strong> arpa_mark and Multiple choice only supported with <code>en-us</code> and <code>en-gb</code> dialects.</em></p></td></tr><tr><td>user_audio_file</td><td>File</td><td><strong>Required.</strong> Max Duration: 30 seconds.<br><em>File with user audio (wav, mp3, m4a, webm, ogg, aiff)</em></td></tr><tr><td>markup_language</td><td>String</td><td><strong>Optional</strong><br><em>Supported values are: <code>arpa_mark</code></em><br><em>Pass this parameter when using markup language in the word parameter.</em><br><br><em><strong>Note:</strong> arpa_mark is only supported with <code>en-us</code> and <code>en-gb</code> dialects.</em></td></tr><tr><td>include_interference_metrics</td><td>String</td><td><p><strong>Optional</strong><br>Use <code>include_interference_metrics=1</code> to include interference metrics in the response. When set, the <code>interference_ratio</code> field is returned inside <code>word_score</code>. <br></p><p>See the <a href="/pages/872216e6aef212f30dc166a8f5384e16b9990a5d">Detecting Speech Interference guide</a> for how to interpret and use this field.<br><br><em><strong>Note:</strong></em> <code>include_interference_metrics</code> <em>is only supported with <code>en-us</code> and <code>en-gb</code> dialects.</em></p></td></tr></tbody></table>

### Request Examples

The below examples show different modes of calling the Score Word API with the responses:

<table><thead><tr><th width="163.21484375">Example</th><th width="282.44140625">Request Body Parameters</th><th>When to Use</th></tr></thead><tbody><tr><td>A. Score a word</td><td><code>word="cat"</code></td><td><em>When scoring a single word and you just want to accept Speechace lexicon for inferring phonetic makeup of the word.</em></td></tr><tr><td>B. Score a word with markup</td><td><code>word="[read]{r iy1 d}"</code><br><code>markup_language="arpa_mark"</code></td><td><em>When you wish to pass the exact expected phonetic markup for the word.</em><br><em>For example in this case you want the present tense of "read" rather than the possibility of present or past tense.</em></td></tr><tr><td>C. Score a word with MC</td><td><code>word="cat\ndog"</code></td><td><em>When you have multiple targets in your activity.</em><br><em>For example, you show 2 pictures of a dog and a cat and the learner speaks their favorite.</em></td></tr><tr><td>D. Score a word with MC and markup</td><td><code>word="[cat]{k ah1 t}\n[dog]{d ao1 g}"</code><br><code>markup_language="arpa_mark"</code></td><td><em>When you have multiple targets but you also wish to explicitly pass the exact phonetic markup for each target.</em></td></tr></tbody></table>

{% hint style="info" %}
You can Review the full arpa\_mark syntax [here](/guides-on-common-topics/markup-language.md#markup-syntax).

**Note:** Score Word relaxes two arpa\_mark syntax constraints:

* Stress is optional (i.e. no 0,1,2 stress required on vowels)
* Syllable boundary is optional (i.e. no '|' required between word syllables)\
  \
  Speechace strongly recommends passing stress and syllable information for best scoring results.
  {% endhint %}

### Response Examples

Below are API response examples for each of the above cases: A, B, C, D.

{% tabs %}
{% tab title="A. word="cat"" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```json
{
    "status": "success",
    "word_score": {
        "word": "cat",
        "quality_score": 98,
        "quality_class": "pass",
        "phone_score_list": [
            {
                "phone": "k",
                "stress_level": null,
                "extent": [
                    11,
                    17
                ],
                "quality_score": 92,
                "sound_most_like": "k"
            },
            {
                "phone": "ae",
                "stress_level": 1,
                "extent": [
                    17,
                    29
                ],
                "quality_score": 100,
                "stress_score": 100,
                "predicted_stress_level": 1,
                "sound_most_like": "ae"
            },
            {
                "phone": "t",
                "stress_level": null,
                "extent": [
                    29,
                    47
                ],
                "quality_score": 100,
                "sound_most_like": "t"
            }
        ],
        "syllable_score_list": [
            {
                "phone_count": 3,
                "stress_level": 1,
                "letters": "cat",
                "quality_score": 97,
                "stress_score": 100,
                "predicted_stress_level": 1,
                "extent": [
                    11,
                    47
                ]
                ]
            }
        ]
    },
    "version": "9.17"
}
```

{% endcode %}
{% endtab %}

{% tab title="B. word="\[read]{r iy1 d}"" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```json
{
    "status": "success",
    "word_score": {
        "word": "read",
        "quality_score": 100,
        "quality_class": "pass",
        "phone_score_list": [
            {
                "phone": "r",
                "stress_level": null,
                "extent": [
                    5,
                    17
                ],
                "quality_score": 100,
                "sound_most_like": "r"
            },
            {
                "phone": "iy",
                "stress_level": 1,
                "extent": [
                    17,
                    29
                ],
                "quality_score": 98,
                "stress_score": 100,
                "predicted_stress_level": 1,
                "sound_most_like": "iy"
            },
            {
                "phone": "d",
                "stress_level": null,
                "extent": [
                    29,
                    41
                ],
                "quality_score": 100,
                "sound_most_like": "d"
            }
        ],
        "syllable_score_list": [
            {
                "phone_count": 3,
                "stress_level": 1,
                "letters": "read",
                "quality_score": 99,
                "stress_score": 100,
                "predicted_stress_level": 1,
                "extent": [
                    5,
                    41
                ]
            }
        ]
    },
    "version": "9.17"
}
```

{% endcode %}
{% endtab %}

{% tab title="C. word="cat\ndog"" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```json
{
    "status": "success",
    "word_score": {
        "word": "cat",
        "quality_score": 98,
        "quality_class": "pass",
        "phone_score_list": [
            {
                "phone": "k",
                "stress_level": null,
                "extent": [
                    11,
                    17
                ],
                "quality_score": 92,
                "sound_most_like": "k"
            },
            {
                "phone": "ae",
                "stress_level": 1,
                "extent": [
                    17,
                    29
                ],
                "quality_score": 100,
                "stress_score": 100,
                "predicted_stress_level": 1,
                "sound_most_like": "ae"
            },
            {
                "phone": "t",
                "stress_level": null,
                "extent": [
                    29,
                    47
                ],
                "quality_score": 100,
                "sound_most_like": "t"
            }
        ],
        "syllable_score_list": [
            {
                "phone_count": 3,
                "stress_level": 1,
                "letters": "cat",
                "quality_score": 97,
                "stress_score": 100,
                "predicted_stress_level": 1,
                "extent": [
                    11,
                    47
                ]
                ]
            }
        ]
    },
    "version": "9.17"
}
```

{% endcode %}
{% endtab %}

{% tab title="D. word="\[cat]{k ah1 t}\n\[dog]{d ao1 g}"" %}
{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```json
{
    "status": "success",
    "word_score": {
        "word": "cat",
        "quality_score": 98,
        "quality_class": "pass",
        "phone_score_list": [
            {
                "phone": "k",
                "stress_level": null,
                "extent": [
                    11,
                    17
                ],
                "quality_score": 92,
                "sound_most_like": "k"
            },
            {
                "phone": "ae",
                "stress_level": 1,
                "extent": [
                    17,
                    29
                ],
                "quality_score": 100,
                "stress_score": 100,
                "predicted_stress_level": 1,
                "sound_most_like": "ae"
            },
```

{% endcode %}
{% endtab %}
{% endtabs %}