apiary.apib

FORMAT: 1A
HOST: https://api-staging.atomicreach.com

# Atomic AI Platform

Developers API Documentation 
http://docs.atomicreach.apiary.io

For more information endpoints and pricing <a class='editorBar__pushButton' href='https://www.atomicreach.com/about/#contact-us' style="color:red">Click Here</a>


## Content Optimization [/content/optimize]

### /content/optimize [POST]

It will return the optimized version of the original body of text / html.
Response data will contain a DOM body that can be compared against the original context with word replacements and alternatives.

+ Request (application/x-www-form-urlencoded)

    + Body

            API_DEMO=1
            &body=%3Cp%3EThis+is+a+test+to+test+the+prototype.%3C%2Fp%3E

+ Parameters
    + body (required, Text/Html (urlencoded), `%3Cp%3EThis+is+a+test+to+test+the+prototype.%3C%2Fp%3E`)
    + contentType (optional, string) - `article` (default), `email`
    + profileId (optional, integer) - Custom scoring profile from AR Platform

+ Response 200 (application/json)

        {
          "status": 10,
          "message": "SUCCESS",
          "data": {
            "body": "<p data-index='0'>This is a <word data-index='3' data-alts='[\"trial\",\"demonstration\",\"show\"]' data-replaced='false'>test</word> to <word data-index='5' data-alts='[\"show\",\"check\",\"measure\"]' data-replaced='true' data-original='test'>prove</word> the <word data-index='7' data-alts='[\"design\",\"model\",\"robot\",\"concept\"]' data-replaced='false'>prototype</word>.</p>\n",
            "replacements": {
              "p-0": {
                "w-5": {
                  "test": "prove"
                }
              }
            },
            "alternatives": {
              "p-0": {
                "w-3": {
                  "test": [
                    "trial",
                    "demonstration",
                    "show"
                  ]
                },
                "w-5": {
                  "test": [
                    "show",
                    "check",
                    "measure"
                  ]
                },
                "w-7": {
                  "prototype": [
                    "design",
                    "model",
                    "robot",
                    "concept"
                  ]
                }
              }
            }
          },
          "execTime": "173 ms"
        }


+ Response 200 (application/json)

        {
            "status": 24,
            "error": "'body' param is required! text/html"
        }



## Real Time Analyze Text API [/analyze-text/master]

### Analyze Text master [POST]

You can analyze a paragraph / text using this action. Supports multiple measures at once via serviceNamesArray.

+ Request (application/json)

        {
            "content": "Once there was a Czar who had three lovely daughters. One day the three daughters went walking in the woods. They were enjoying themselves so much that they forgot the time and stayed too long. A dragon kidnapped the three daughters. As they were being dragged off they cried for help. Three heroes heard their cries and set off to rescue the daughters. The heroes came and fought the dragon and rescued the maidens. Then the heroes returned the daughters to their palace. When the Czar heard of the rescue, he rewarded the heroes.",
            "serviceNamesArray": [
                "paragraph_density", // returns paragraphDensityArray
                "sentence_length",   // returns sentenceLengthIssuesArray
                "spelling",          // returns issuesArray
                "grammar",           // returns issuesArray
                "readability",       // calculates Syntax / audience level of the text | automatically done if context / synonyms are enabled
                "keywords",          // returns keywordsArray
                "synonyms_v3",       // returns synonymsV3 by Context / best match on top
                "urls"               // checks links in html | returns urlsArray
            ],
            "sophisticationBandId": 4, // target audience level | 1,2,3,4,5 | optional | set to Knowledgeable by default
            "contentHtml": "" // optional, only required if urls service is active
        }

+ Response 200 (application/json)

    + Headers

            Location: /analyze-text/master

    + Body

            {
                "status": 10,                   // OK
                "detail": "TOO SIMPLE",         // TOO SIMPLE | TOO COMPLEX for the target audience | readability
                "actual": "General",            // the actual audience of the paragraph | readability
                "target": "Knowledgeable",      // the target audience of the paragraph | readability
                "paragraphDensityArray": [...], // paragraph length issues
                "sentenceLengthIssuesArray": [...],
                "issuesArray": [...],           // Spelling & Grammar issues
                "keywordsArray": [...],         // keywords detected in the paragraph
                "synonymsV3": [...],            // Synonyms, synset definitions, word emotion / intensity
                "urlsArray": [...],             // valid / invalid links
            }
            
            

### Paragraph density [POST]

+ Request (application/json)

        {
            "content": "Once there was a Czar who had three lovely daughters. One day the three daughters went walking in the woods. They were enjoying themselves so much that they forgot the time and stayed too long. A dragon kidnapped the three daughters. As they were being dragged off they cried for help. Three heroes heard their cries and set off to rescue the daughters. The heroes came and fought the dragon and rescued the maidens. Then the heroes returned the daughters to their palace. When the Czar heard of the rescue, he rewarded the heroes.",
            "serviceNamesArray": [
                "paragraph_density"
            ],
            "sophisticationBandId": 4
        }

+ Response 200 (application/json)

    + Headers

            Location: /analyze-text/master

    + Body

            {
                "status": 10,
                "paragraphDensityArray": 
                {
                    "maxWordsPerParagraph": 
                    {
                        "current": 94,
                        "maximum": 65,
                        "passed": false
                    },
                    "maxCharsPerParagraph": 
                    {
                        "current": 532,
                        "maximum": 264,
                        "passed": false
                    },
                    "passed": false
                }
            }
        

### Sentence length [POST]

+ Request (application/json)

        {
            "content": "Once there was a Czar who had three lovely daughters one day the three daughters went walking in the woods. They were enjoying themselves so much that they forgot the time and stayed too long a dragon kidnapped the three daughters. As they were being dragged off they cried for help. Three heroes heard their cries and set off to rescue the daughters. The heroes came and fought the dragon and rescued the maidens. Then the heroes returned the daughters to their palace. When the Czar heard of the rescue, he rewarded the heroes.",
            "serviceNamesArray": [
                "sentence_length"
            ],
            "sophisticationBandId": 4
        }

+ Response 200 (application/json)

    + Headers

            Location: /analyze-text/master

    + Body

            {
              "status": 10,
              "sentenceLengthIssuesArray":
              [
                {
                  "string": "in the woods",
                  "precontext": "",
                  "wordsCountOverload": 3
                },
                {
                  "string": "kidnapped the three daughters",
                  "precontext": "",
                  "wordsCountOverload": 4
                }
              ]
            }
            

### Spelling issues [POST]

+ Request (application/json)

        {
            "content": "Once there was a Czar who had three lovely daughsters. One day the three daughters went walking in the woods.They were enjoying themselves so much that they forgot the time and stayed too long. A dragon kidnapped the three daughters. As they were being dragged off they cried for help. Three heroes heard their cries and set off to rescue the daughters. The heroes came and fought the dragon and rescued the maidens. Then the heroes returned the daughters to their palace. When the Czar heard of the rescue, he rewarded the heroes.",
            "serviceNamesArray": [
                "spelling"
            ],
            "sophisticationBandId": 4
        }

+ Response 200 (application/json)

    + Headers

            Location: /analyze-text/master

    + Body

            {
              "status": 10,
              "issuesArray": [
                {
                  "string": "daughsters",
                  "precontext": "lovely",
                  "suggestions": [
                    [
                      "Possible spelling mistake found",
                      [
                        [
                          "daughters"
                        ]
                      ]
                    ]
                  ],
                  "type": "spelling"
                },
                {
                  "string": "They",
                  "precontext": "woods.",
                  "suggestions": [
                    [
                      "Add a space between sentences",
                      [
                        [
                          " They"
                        ]
                      ]
                    ]
                  ],
                  "type": "spelling"
                }
              ]
            }
            

### Grammar issues [POST]

+ Request (application/json)

        {
            "content": "Once there was a Czar who had three lovely daughters. One day the three daughters went walking in the woods. They were enjoying themselves so much that they forgot the time and stayed too long. A dragon kidnapped the three daughters. As they were being dragged off they cried for help. Three heroes heard their cries and set off to rescue the daughters. The heroes came and fought the dragon and rescued the maidens. Then the heroes returned the daughters to their palace. When the Czar heard of the rescue, he rewarded the heroes.",
            "serviceNamesArray": [
                "grammar"
            ],
            "sophisticationBandId": 4
        }

+ Response 200 (application/json)

    + Headers

            Location: /analyze-text/master

    + Body

            {
              "status": 10,
              "issuesArray": [
                {
                  "string": "Once",
                  "precontext": "",
                  "suggestions": [
                    [
                      "\u201cOnce\u201d at the beginning of a sentence requires a 2nd clause. Maybe a comma, question or exclamation mark is missing, or the sentence is incomplete and should be joined with the following sentence. ",
                      []
                    ]
                  ],
                  "type": "grammar"
                },
                {
                  "string": "were being dragged",
                  "precontext": "they",
                  "suggestions": [
                    [
                      "Passive voice",
                      []
                    ]
                  ],
                  "type": "grammar"
                }
              ]
            }


### Keywords [POST]

+ Request (application/json)

        {
            "content": "Once there was a Czar who had three lovely daughters. One day the three daughters went walking in the woods. They were enjoying themselves so much that they forgot the time and stayed too long. A dragon kidnapped the three daughters. As they were being dragged off they cried for help. Three heroes heard their cries and set off to rescue the daughters. The heroes came and fought the dragon and rescued the maidens. Then the heroes returned the daughters to their palace. When the Czar heard of the rescue, he rewarded the heroes.",
            "serviceNamesArray": [
                "keywords"
            ],
            "sophisticationBandId": 4
        }

+ Response 200 (application/json)

    + Headers

            Location: /analyze-text/master

    + Body

            {
              "status": 10,
              "keywordsArray": [
                "daughters",
                "Czar",
                "heroes",
                "dragon"
              ]
            }


### Contextual Synonym suggestions [POST]

+ Request (application/json)

        {
            "content": "We test the test site and it looks good.",
            "serviceNamesArray": [
                "synonyms_v3"
            ],
            "sophisticationBandId": 4
        }

+ Response 200 (application/json)

    + Headers

            Location: /analyze-text/master

    + Body

            {
              "status": 10,
              "synonymsV3": {
                "synAll": [...],                   // all synonym syggestions
                "synLowerAudience": [...],         // suggestions to Decrease the audience level of the text
                "synSameAudience": [...],          // suggestions to keep the same the audience level
                "synHigherAudience": [...],        // suggestions to Increase the audience level
                "synAllByEm": [...],               // all synonyms ordered by Emotion / Intensity
                "synEmotionLowerAudience": [...],  // decrease audience, by Emotion / Intensity
                "synEmotionSameAudience": [...],   // keep same audience, by Emotion / Intensity
                "synEmotionHigherAudience": [...], // increase audience, by Emotion / Intensity
                "synEmotionAdvAdj": [...]          // Adverbs / Adjectives, by Emotion / Intensity
              }
            }

    
### Synonyms response explained [POST]

+ Request (application/json)

        {
            "content": "We test the test site and it looks good.",
            "serviceNamesArray": [
                "synonyms_v3"
            ],
            "sophisticationBandId": 4
        }

+ Response 200 (application/json)

    + Headers

            Location: /analyze-text/master

    + Body

    {
        "synAll": [ // all synonyms response array | contains all paragraphs processed, each paragraph as an object
            
            { // first paragraph object
            
                "test": 
                [ // first word we can offer suggestions for
                  // if the word appears multiple times within the text, this array will contain additional items
                  // in this case, the word is a Verb at the first occurrence, then a Noun on the second occurrence
                
                  [ // first occurrence of the word in the paragraph | we've determined the word is a VERB
                    
                    [ // first synonym set suggestion | this is a ranking as well, with the sets on top as most relevant
                    
                      "determine the result of (a competition)", // the definition on the synonym set
                      
                      [ // the collection of words in this synonym set | we might find multiple matches with the same set
                        [ // first suggested word for replacement
                          "judge"
                        ]
                      ]
                    ],
                    [ // second synonym set
                    
                      "establish after a calculation, investigation, experiment, survey, or study",
                      [
                        // we found 3 words in this set that might work
                        [
                          "determine"
                        ],
                        [
                          "ascertain"
                        ],
                        [
                          "find out"
                        ]
                      ]
                    ],
                    ["..."] // other suggestions follow
                    
                  ], // end first occurrence
                  
                  [ // second occurrence | we've determined the word is a NOUN this time...
                  
                    [
                      "the act of examining something closely (as for mistakes)",
                      [
                        [
                          "examination"
                        ]
                      ]
                    ],
                    [
                      "a set of questions or exercises evaluating skill or knowledge",
                      [
                        [
                          "exam"
                        ]
                      ]
                    ],
                    ["..."] // other suggestions follow

                  ] // end second occurrence
                
                ], // end first word
                
                "site": 
                [ // the second word we can offer suggestions
                 [ // first occurrence
                    [
                      "a point located with respect to surface features of some region",
                      [
                        [
                          "place"
                        ]
                      ]
                    ],
                    [
                      "a computer connected to the internet that maintains a series of web pages on the World Wide Web",
                      [
                        [
                          "website"
                        ],
                        [
                          "web site"
                        ]
                      ]
                    ],
                    ["..."] // other sets follow...
                 ]
                ],
                "looks": ["..."],
                "good": ["..."]
            } 
        ],
        // the response for the other synonym measures is in the same format as above
        "synLowerAudience": ["..."],
        "synSameAudience": ["..."],
        "synHigherAudience": ["..."],
        "synAllByEm": [
            {
                "test":  
                [
                    [ // first occurrence | VERB
                        [
                          "gain points in a game",
                          [
                            [
                              "score",
                              "+"      // + means more word emotion / intensity, while - means less intensity
                            ]
                          ]
                        ],
                        [
                          "examine someone's knowledge of something",
                          [
                            [
                              "quiz",
                              "+"     // + | -
                            ]
                          ]
                        ],
                        ["..."]
                    ],
                    [ // second occurrence | NOUN
                        [
                          "an examination consisting of a few short questions",
                          [
                            [
                              "quiz",
                              "+"      // + | -
                            ]
                          ]
                        ],
                        [
                          "the act of examining something closely (as for mistakes)",
                          [
                            [
                              "examination",
                              "+"
                            ]
                          ]
                        ],
                        ["..."]
                    ]
                ],
                "site": 
                [
                 [
                    [
                      "the act of digging",
                      [
                        [
                          "excavation",
                          "+"            // + means more word emotion / intensity, while - means less intensity
                        ]
                      ]
                    ],
                    [
                      "a point located with respect to surface features of some region",
                      [
                        [
                          "place",
                          "-"          // - means less emotion / intensity here
                        ]
                      ]
                    ],
                    ["..."] // other sets follow...
                 ]
                ],
                "looks": ["..."],
                "good": ["..."]
                
            }
        ],
        "synEmotionLowerAudience": ["..."],
        "synEmotionSameAudience": ["..."],
        "synEmotionHigherAudience": ["..."],
        "synEmotionAdvAdj": ["..."]
    }


### Check links / urls [POST]

+ Request (application/json)

        {
            "contentHtml": "We test the test site and it looks good. <a href='https://www.googlebroken.com'>broken link</a> <a href='http://www.atomicreach.com/blog/'>good link</a>",
            "serviceNamesArray": [
                "urls"
            ]
        }

+ Response 200 (application/json)

    + Headers

            Location: /analyze-text/master

    + Body

            {
              "status": 10,
              "urlsArray": [
                {
                  "url": "https:\/\/www.googlebroken.com",
                  "valid": false
                },
                {
                  "url": "http:\/\/www.atomicreach.com\/blog\/",
                  "valid": true
                }
              ]
            }
            
            
## Document / Readability [/analyze-text/get-readability]

Analyze the readability of a document / text. Can be used to identify the audience level of a whole document to get a global reference.


### /get-readability [POST]

Send either 'documentDataArray' | 'contentHtml' | 'content'. It is important to specify the paragraphs to the API in order to get an accurate audience level.

'documentDataArray' should be an array of text values, witch each item containing a paragraph text.

'contentHtml' should be a block of text containing the tag \<p\>\</p\> for each paragraph. Optionally, you can send full HTML here, but it's not as efficient.

+ Request (application/json)

        {
            "documentDataArray": [
                "Creating assets that they can print out or physically use in their own strategy proves to increase the value of your ebook.",
                "Provide them with the tools and resources to help them take action.",
                "This strategy can also create an opening to naturally add your tool/product to the ebook."
            ],
            "contentHtml": "<p>Creating assets that they can print out or physically use in their own strategy proves to increase the value of your ebook.</p><p>Provide them with the tools and resources to help them take action.</p><p>This strategy can also create an opening to naturally add your tool/product to the ebook.</p>",
            "sophisticationBandId": 5
        }

+ Response 200 (application/json)

    + Headers

            Location: /analyze-text/get-readability

    + Body

            {
                "status": 10,
                "detail": "TOO SIMPLE", // "TOO SIMPLE" | "TOO COMPLEX" | "HIT"
                "actual": "Knowledgeable",
                "target": "General"
            }
            

## Document / Keywords [/analyze-text/get-keywords]

### /get-keywords [POST]

parameters: 'content' | 'contentHtml' | 'documentDataArray'

+ Request (application/json)

        {
            "contentHtml": "<p>Creating assets that they can print out or physically use in their own strategy proves to increase the value of your ebook.</p><p>Provide them with the tools and resources to help them take action.</p><p>This strategy can also create an opening to naturally add your tool/product to the ebook.</p>"
        }

+ Response 200 (application/json)

    + Headers

            Location: /analyze-text/get-keywords

    + Body

            {
              "status": 10,
              "keywordsArray": [
                "ebook",
                "strategy",
                "print",
                "increase",
                "resources",
                "action",
                "tools"
              ]
            }
            

## Document / Analysis [/post/analyze]

### /post/analyze [POST]

Required params: 
- 'title' -> document title, it will influence score
- 'content' -> should be a block of text containing the tag \<p\>\</p\> for each paragraph. Will accept HTML as well.
- 'sophisticationBandId' -> target audience level

Response will contain Atomic Score for the document / analysis will contain more detailed information. Response time should be ~= 1 second for each 1k words.

+ Request (application/json)

        {
            "title": "How To Make That Boring Ebook Standout?",
            "content": "<p>Creating assets that they can print out or physically use in their own strategy proves to increase the value of your ebook.</p><p>Provide them with the tools and resources to help them take action.</p><p>This strategy can also create an opening to naturally add your tool/product to the ebook.</p>",
            "sophisticationBandId": 4
        }

+ Response 200 (application/json)

    + Headers

            Location: /post/analyze

    + Body

            {
              "status": 10,
              "data": {
                "scoring": 57,
                "analysis": {
                  "pee": {}, // plain English errors
                  "ste": {}, // style errors
                  "pue": {}, // punctuation errors
                  "lw": {},  // linguistic warnings
                  "le": {},  // linguistic errors
                  "em": {},  // emotion
                  "lr": {},  // compression
                  "tg": {},  // keywords / topics
                  "su": {},  // surprise
                  "lc": {},  // urls
                  "tm": {},  // title
                  "tq": {},  // titleQuestion
                  "tpp": {}, // titlePronoun
                  "ln": {},  // length
                  "gm": {},  // grammar mistakes
                  "sem": {}, // semantic mistakes
                  "pwd": {}, // paragraph density
                  "sm": {},  // spelling mistakes
                  "so": {}   // readability
                }
              }
            }