How to use summarization API?

11. Jan 2018

iamcalm.online API lets you get any Summarization Result through a simple Application Programming Interface (API).

Let’s help you get started.

Introduction

Endpoints

iamcalm.online API endpoints are located at https://iamcalm.online/api/v1. From there on, you can access a logical structure that adheres to the REST standards.

Responses

All responses from the API are formatted as JSON.

Authorization

Get your API Token

Once you are logged in navigate to API Access and create your API token. Once you have the token, you can authenticate against the API.

Authenticate against the API

The token you have been given can be used as the Bearer authentication header. Here is a curl example of how you can authenticate against the API.

curl -X "POST" "https://iamcalm.online/api/v1/status" \
     -H 'Authorization: Bearer a0ac8ae866e64e2faa26c9f733cf1f34'

The token a0ac8ae866e64e2faa26c9f733cf1f34 is used to authenticate you. The resulting response payload may look like this.

{
    "message":"OK",
    "details": {
        "words-read-last-7-days":19721145
        ...
    }
}

Summarization

There are 3 endpoints to get our Summarization, based on what you want to retrieve:

  • /api/v1/highlights
  • /api/v1/keywords
  • /api/v1/summary

Request data

All of those endpoints accept same type of payload:

Text

If you want to summarize text, pass the text field in your payload like this

{
    “text”: “text you want to summarize”
}

Here is curl example:

curl -X "POST" "http://iamcalm.localhost/api/v1/keywords" \
     -H 'Authorization: Bearer a0ac8ae866e64e2faa26c9f733cf1f34' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
        "text": "foo"
    }'

Url

If you want to summarize web page, pass the url field in your payload like this

{
    “url”: “http://example.com”
}

Here is curl example:

curl -X "POST" "http://iamcalm.localhost/api/v1/keywords" \
     -H 'Authorization: Bearer a0ac8ae866e64e2faa26c9f733cf1f34' \
     -H 'Content-Type: application/json; charset=utf-8' \
     -d $'{
        "url": "http://example.com"
     }'

Please, be aware that scraping the web page make take a while.

File

If you want to summarize file content via API, post the file as FormData file field. Here is curl example:

curl -X "POST" "http://iamcalm.localhost/api/v1/highlights" \
     -H 'Authorization: Bearer a0ac8ae866e64e2faa26c9f733cf1f34' \
     -F "[email protected]/home/user/sample.txt"

Please note we accept plain text, MS Word, PDF, and Rich Text Documents. As you know, it’s an issue itself to parse such a document files. Please, read about cons of parsing documents here.

Endpoints and their Responses

Highlights

To get highlights of given request data, make POST request to the https://iamcalm.online/api/v1/highlights endpoint. It returns an array of Keywords with their corresponding score (1 .. 0, higher score means higher relevance) sorted from highest importance descendant to lowest.

Like in this example:

{
    “highlights”: [
        "Artificial Intelligence is a complex riddle for all sorts of experts.",
        "There is little doubt that machines will out-simulate and outperform human intelligence at any specific contest.",
        "Whatever point in time machines outperform the human brain in totality does not matter.",
        "Technology is made to make our life easier, to serve us.",
        ...
    ]
}

Keywords

To get highlights of given request data, make POST request to the https://iamcalm.online/api/v1/keywords endpoint. It returns an array of Keywords with their corresponding score (1 .. 0, higher score means higher relevance) sorted from highest importance descendant to lowest.

Like in this example:

{
    “keywords”: [
        "Machines": 1,
        "Make": 0.8795955882352942,
        "Human": 0.6488970588235294,
        "Intelligent": 0.3961397058823529,
        ...
    ]
}

Summary

As you probably expect, the Summary endpoints in the same way. Post your Request input to the summary endpoint https://iamcalm.online/api/v1/summary, and you will get an array of summary sentence, like this for example:

{
    “keywords”: [
        "In order to make existential decisions for us, we need them to understand us, to relate to us, to be like us, and for that, they need a human body.",
        "Understanding is feeling what you think.",
        "What is human and who is machine."
    ]
}

That’s it, for now.

Happy coding.

And happy days of course.


Last week Oli saved 24 minutes every day to every of our customers. It is 15.697.760 words of reading in total.