OpenAdvocate WriteClearly
Developer Documentation

WriteClearly provides an API interface that can be used by third-partyapplications to submit text to WriteClearly for analysis. This document describes how to use the WriteClearly API.

Making Requests

Use the following endpoint to make requests:

http://writeclearly.openadvocate.org/oawc/service.php

The endpoint expects POST requests in JSON format. The JSON object in the request body should contain the following attributes: “content”: The text to be analyzed. The content may be in HTML or plain text format.

“json”: Should be set to 1 to receive a JSON response.

Example:

{
  "content" : "Hello world",
  "json" : 1
}

Response:

The analysis is sentence based. For each sentence where WriteClearly is able to make a suggestion, it will return the original sentence, and a summary of suggestions made in the given sentence.

The response JSON object contains the following attributes:

“suggestions”: An array of suggestions. Each suggestion contains the following attributes:

“paragraph_id”: The id of the paragraph in which the suggestion was found, if it can be identified.

“content”: The original sentence, with added HTML markup.

“summary”: A textual summary of the suggestions made in the given sentence.

Example:

{  
  "index": 7.43,
  "suggestions": [
    {  
      "summary": "Replace polysyllabic words where possible.",
      "content": "Bankruptcy is usually
        <span class="wc-poly-container"> 
          <span class="wc-hinted" data-word="considered">considered</span>             
          <span class="wc-hint wc-synonym">
            Synonyms:
            <span class="wc-replace-word">knowing</span>,
            <span class="wc-replace-word">studied</span>,
            <span class="wc-replace-word">thoughtful</span>
          </span>
        </span> 
        a last resort option.",
      "paragraph_id": "oawc-p-1"
    }
  ]
}

If present, <p> HTML tags in the source text will help WriteClearly identify paragraphs. The <p> tags may contain the class “oawc-p-[id]”, where [id] is
arbitrary number. When this class is found, the response will contain this
identifier in the returned response. Otherwise, the paragraph_id attribute
will be empty.

The sentence in the “content” attribute is marked up with HTML. Each word in the original sentence that has a corresponding suggestion is wrapped in a element with the “wc-hinted” class. This may be used in CSS styles to highlight the word. In addition, polysyllabic words for which synonyms are offered are wrapped in a element with the “wc-poly-container” class. This element will wrap the word to which the suggestion belongs, as well as a list of suggested synonyms enclosed in a element with the “wc-hint” class. These will need to be styled to appear consistently with your site’s theme. If you do not wish to show them, apply a CSS rule that hides elements with the “wc-hint” class.

OpenAdvocate WriteClearlyDeveloper Documentation

Making Requests

Example:

Response:

Example:

OpenAdvocate WriteClearly
Developer Documentation