ProWritingAid API Documentation

The ProWritingAid text processing API provides a simple RESTful interface with lightweight JSON-formatted responses to use many of the ProWritingAid website features. This document provides information for developers on how to integrate with the ProWritingAid API to access our powerful text processing API.

API Basics

Before you can use our API you must sign up for an account and then register for a developer License Key. The key identifies your application to the ProWritingAid web service, and is used to track overall call usage.

API Errors

In the event of an authorization error the call will return a Http Status Code of 403 (Forbidden) and the error message as the content.

In the event of an internal error the call will return a Http Status Code of 500 (Internal Server Error)

In the event of a badly formed request the call will return a Http Status Code of 400 (Bad Request) - NB. This may occur if your Content-Type is not set to application/json

API Request Headers

All API requests are made using JSON object. You must ensure that your request header contains a Content-Type: application/json

http://prowritingaid.com/en/APIv1/Analyze

Submits a text to be analyzed with a list of reports for which the tags should be included in the response. Returns a set of tags and a summary for each report.

REQUEST
{ "licenceCode":"037C1C6B-6CB1-494E-8AA9-58669694B830", "reports":"phrases,overused", "text":"Once there was a story to be analyzed...", "style":"1" }
Parameter Description
licenceCode Your access code, used to track usage.
reports The name of the reports that you want to include in the output of the API call (see below for a full list).
text The text that you want to analyze
style The writing style you want the analysis for: General=1 Academic=2 Business=3 Technical=4 Creative=5 Causual=6 Web=7.
RESPONSE
{ "tags":[ { "startPos":"11", "endPos":"13", "report":"overused", "category":"overusedWasWere", "subcategory":"", "hint":"Overused try removing 5 occurrences", "suggestions":"", "isSubTag":"false", }], "summaries":[ { "reportName":"overused", "reportDescription":"The overused words report...", "reportDisplayName":"Overused Words Report", "numIssuesFound":"1", "helplink":"help.aspx?page=overused", "items":[ { "state":"1", "text":"was/were remove about 8 occurrences", "subcategory":"overusedWasWere", "isPositive":"false", "subitems":[ { "text":"Example text", "subcategory":"overusedWasWere", }] }] }] }

Details of the Analysis Response Object

Parameter Description
tags An array of Tags for the text you submitted.
summaries A array of Report Summaries for the reports that your requested.

Details of the Tag Object

Parameter Description
startPos The zero based index into the text of the start of the tag.
endPos The zero based index into the text of the end of the tag.
report The name of the report to which the tag belongs.
category The broad category of the tag.
subCategory The more specific sub-category of the tag.
hint A hint to the user associated with the tag, e.g. remove about 8 occurrences.
suggestions A comma separated string of suggestions for replacements.
isSubTag A boolean denoting wether this is a sub-tag. Used for example in the sticky sentences report to denote sticky words.

Details of the Report Summary Object

Parameter Description
reportName The report name. Same as in the request (see below for a list of available reports).
reportDisplayName A name of the report that the user will uderstand.
reportDescription A longer description of what the report is ment to show.
numIssuesFound The number of issues that have been found for this report.
items An array of Report Summary Items for this report. Each item corresponds to one check made for the report, e.g. Average Sentence Length < x%
helpLink A reference to a page on our website with help information for this report

Details of the Report Summary Item Object

Parameter Description
isPositive (Deprecated) Is the item positive (or information), use the state to determine this now.
state A state for this item. Positive = 1, Negative = 2, Information = 3.
text The text for this summary item.
subCategory A specific category relating to this item, can be used to link to the relevant tags.
subItems An array of Report Summary Sub Items.

Details of the Report Summary SubItem Object

Parameter Description
text The text for this summary sub item.
subCategory A specific category relating to this subitem, can be used to link to the relevant tags.

Available Reports

Below is a list of the currently available reports from ProWritingAid. If you would like a different report, or require extra information, such as tokenization, sentence split, parts of speech, etc. then please get in touch.

Report Name Status Description
acronym Live Shows all the acronyms in your writing and highlights where they haven't been defined, or have been defined after the first occurrence, or have been defined multiple times..
alliteration Live Highlights alliterations in your writing. Alliterations are a linguistic tool used by some writers for effect..
allrepeats Development Highlights words and phrases that you've used repeatedly in your text.
allsentences Live Shows a visual representation of the sentences lengths of your writing. Try and vary the sentence lengths to maintain the interest of the reader..
bully Development Highlights bullying and vulgar language in your text..
cliche Live Scours your work for cliches and highlights them. Nobody likes to read a cliche so best to avoid them. Redundant expressions can also be removed as they say the same thing twice..
closerepeat Development Highlights any words and phrases that you have repeated within a short space of writing. Try and think of something else to say..
complex Live Highlights complex words in your writing. Words are broken down by number of syllables..
consistency Live Highlights inconsistency in your text. Picking up inconsistencies in your text can be one of the hardest editing tasks..
core Development Core findings.
coreplus Development Core findings.
corporate Live Highlights uses of corporate wording that can be simplified to clarify your document..
dialog Live Highlights the dialogue tags in your text. Editors prefer minimal use of all dialogue tags (except for 'said')..
diction Live Provides a list of possible diction problems and suggestions on how you might revise them..
dva Live Highlights diction problems, vague and abstract words in your text..
eloquence Live Designed to help you develop your use of stylistic writing techniques such as alliteration, epistrophe, and hendiadys. The items in this report are not suggestions, just aids to help you along the way..
grammar Live Checks your text for grammar errors and potential word mis-use..
grammarplus Live Checks your text for grammar errors and potential word mis-use..
homonym Live Helps you check for incorrect word usage. Homonyms are words which sound alike yet are spelled differently. For example: there, their and they're or raw and roar..
house Development A blank report for you to create your own patterns in. Ideal for a house style. Go to the settings screen to set-up your own patterns. .
initial Live Highlights the initial pronouns in your text. Repetitive use of initial pronouns can lead to boring text, e.g. He did this. He did that. He did another thing..
nlp Development Our NLP Predicate Words report allows you to easily identify the key modality or representation system of a piece of text. If you are analyzing a document written by someone else then this will give you an idea of their preferred representational system. This may help you tailor your writing in order to build rapport. If you don't know the modality of your reader then try to use a balance of words from each modality. This will broaden the appeal of your writing..
overused Live Compares the frequency of commonly overused words in your text to published writing to give you an indication of where you may be over-using words..
overusedonly Live Compares the frequency of commonly overused words in your text to published writing to give you an indication of where you may be over-using words..
overview Live Gives you an overview of the key metrics for your document..
pacing Live Identifies the slower paced parts of your manuscript, such as introspection and backstory so you can spread them out. Try not to have too many slower paced paragraphs in a row as this can get boring..
paragraph_readability Live Shows you the relative readability of each paragraph in your text..
passive Live Highlights areas where your writing style might be improved, such as use of passive and hidden verbs..
phrases Live Provides a summary of all the phrases that you have repeated in your writing. Try and cut down on repeats..
plagiarism Live Identifies parts of your text that occur in other documents. Scans millions of web-pages, books, and academic papers..
plength Live A visual representation of the paragraph lengths of your writing. Avoid writing more than five or six sentences in a paragraph. Also try to avoid too many short paragraphs..
preadability Live Provides a series of readability measures for your text so you can determine if it is suitable for your intended audience..
readability Live Provides a series of readability measures for your text so you can determine if it is suitable for your intended audience..
sentiment Live Shows a histogram of the sentiment in your story so you can monitor large swings..
sentimentwords Development Highlights words that have a sentiment bias in your text, and grades them..
seo Development Shows how yout text can be optimized to appear higher in Google rankings..
slength Live Shows a visual representation of the sentences lengths of your writing. Try and vary the sentence lengths to maintain the interest of the reader..
ssentences Live Shows sticky sentences in your writing. Sticky sentences slow your reader down; try to avoid them..
ssentences_noglue Live Shows sticky sentences in your writing. Sticky sentences slow your reader down; try to avoid them..
structure Live Highlights the key structure of a document such as sentences and paragraphs..
term Live Highlights all the terms in your text. You can specify preferred, allowed and deprecated terms in your TermBase in your user or team settings..
thesaurus Beta Shows possible replacements for nouns, verbs, adjectives and adverbs..
time Live Highlights any temporal references in your text so you can check for inconsistency and view the time-line of your text..
topics Live Suggested topics that are related to the subject matter of your text..
transition Live Highlights the transitions in your report. Transitions help organize ideas. Writing that is short on transitions is often hard to follow. Non-fiction writing that has under 1 transition per 4 sentences tends to be less understandable..
vague Live Provides a list of words that may be considered vague or abstract. Consider strengthening them..
wordcloud Live Shows you a word cloud of the most commonly occuring words in your text..
wordsandphrases Deprecated Highlights any words and phrases that you have repeated within a short space of writing. Try and think of something else to say..
wordsphrases Live Highlights any words and phrases that you have repeated within a short space of writing. Try and think of something else to say..

Other methods

There are other methods available that will accept HTML input and return HTML with all relevant tags added for a particular report. If you are interested in these methods then please get in touch