Edit

Translator 3.0: BreakSentence

  • Article

Identifies the positioning of sentence boundaries in a piece of text.

Request URL

Send a POST request to:

https://api.cognitive.microsofttranslator.com/breaksentence?api-version=3.0

See Virtual Network Support for Translator service selected network and private endpoint configuration and support.

Request parameters

Request parameters passed on the query string are:

Query Parameter Description
api-version Required query parameter.
Version of the API requested by the client. Value must be 3.0.
language Optional query parameter.
Language tag identifying the language of the input text. If a code isn't specified, automatic language detection is applied.
script Optional query parameter.
Script tag identifying the script used by the input text. If a script isn't specified, the default script of the language is assumed.

Request headers include:

Headers Description
Authentication header(s) Required request header.
See available options for authentication.
Content-Type Required request header.
Specifies the content type of the payload. Possible values are: application/json.
Content-Length Required request header.
The length of the request body.
X-ClientTraceId Optional.
A client-generated GUID to uniquely identify the request. You can omit this header if you include the trace ID in the query string using a query parameter named ClientTraceId.

Request body

The body of the request is a JSON array. Each array element is a JSON object with a string property named Text. Sentence boundaries are computed for the value of the Text property. A sample request body with one piece of text looks like that:

[
    { "Text": "How are you? I am fine. What did you do today?" }
]

The following limitations apply:

  • The array can have at most 100 elements.
  • The text value of an array element can't exceed 50,000 characters including spaces.
  • The entire text included in the request can't exceed 50,000 characters including spaces.
  • If the language query parameter is specified, then all array elements must be in the same language. Otherwise, language autodetection is applied to each array element independently.

Response body

A successful response is a JSON array with one result for each string in the input array. A result object includes the following properties:

  • sentLen: An array of integers representing the lengths of the sentences in the text element. The length of the array is the number of sentences, and the values are the length of each sentence.

  • detectedLanguage: An object describing the detected language through the following properties:

    • language: Code of the detected language.

    • score: A float value indicating the confidence in the result. The score is between zero (0) and one (1.0). A low score (<= 0.4) indicates a low confidence.

The detectedLanguage property is only present in the result object when language autodetection is requested.

An example JSON response is:

[
    {
        "detectedLanguage": {
            "language": "en",
            "score": 1.0
        },
        "sentLen": [
            13,
            11,
            22
        ]
    }
]

Response headers

Headers Description
X-RequestId Value generated by the service to identify the request. It's used for troubleshooting purposes.

Response status codes

The following are the possible HTTP status codes that a request returns.

Status Code Description
200 Success.
400 One of the query parameters is missing or not valid. Correct request parameters before retrying.
401 The request couldn't be authenticated. Check that credentials are specified and valid.
403 The request isn't authorized. Check the details error message. This response code often indicates that all free translations provided with a trial subscription have been used up.
429 The server rejected the request because the client has exceeded request limits.
500 An unexpected error occurred. If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.
503 Server temporarily unavailable. Retry the request. If the error persists, report it with: date and time of the failure, request identifier from response header X-RequestId, and client identifier from request header X-ClientTraceId.

If an error occurs, the request returns a JSON error response. The error code is a 6-digit number combining the 3-digit HTTP status code followed by a 3-digit number to further categorize the error. Common error codes can be found on the v3 Translator reference page.

Examples

The following example shows how to obtain sentence boundaries for a single sentence. The service automatically detects the sentence language.

curl -X POST "https://api.cognitive.microsofttranslator.com/breaksentence?api-version=3.0" -H "Ocp-Apim-Subscription-Key: <client-secret>" -H "Content-Type: application/json" -d "[{'Text':'How are you? I am fine. What did you do today?'}]"