Getting your Topics


Beta: This feature is currently in beta. Please contact Support to enable it.
This quickstart demonstrates how to load an audio or video file and request your topics in a few minutes.

Configuring Your Environment

While you can use any programming language you choose, we provide a few helper libraries to get you started. In most cases, you can use your favorite package manager:

  • curl
Although we don't have a curl library, the command-line JSON parser 'jq' is super helpful. Download and install it to get started: http://stedolan.github.io/jq/

Loading Audio

First include the SDK and create your object using your API Key. Once you’ve created the object, you can use the object to load each of your audio files as shown:

  • curl
curl --data "media_url=http://media.clarify.io/audio/books/dorothyandthewizardinoz_01_baum_64kb.mp3" \
     --data "notify_url=http://example.org/sample-receiver" \
     --data "name=Dorothy and the Wizard of Oz" https://api.clarify.io/v1/bundles \
     --X POST --header "Authorization: Bearer myapikey" | jq '.'
# The jq portion is optional and just used to pretty print the resulting json

Naming the bundle and providing a notify_url are both optional. We have a number of audio and video files available for processing on our Media Page.

Note: You don't have to download these files. Instead you can pass the urls via the create/POST method shown above.
After creating a bundle, you'll receive a response which looks something like this:
{
    "id":"abcde12345",
    "_class":"Ref",
    "_links":{
        "self":{
            "href":"/v1/bundles/abcde12345"
        },
        "curies":[
            {
                "href":"/docs/rels/{rel}",
                "name":"clarify",
                "templated":true
            }
        ],
        "clarify:metadata":{
            "href":"/v1/bundles/abcde12345/metadata"
        },
        "clarify:tracks":{
            "href":"/v1/bundles/abcde12345/tracks"
        },
        "clarify:insights":{
            "href":"/v1/bundles/abcde12345/insights"
        }
    }
}

Getting your Topics

The most important part of the bundle notification is the href of the clarify:insights key. By retrieving the contents of that URI, Clarify will give you a list of the Insights available.
  • curl
curl https://api.clarify.io/v1/bundles/abcde12345/insights \
     --header "Authorization: Bearer myapikey"  | jq '.'
# The jq portion is optional and just used to pretty print the resulting json
This will return with the list of available insights:
{
    "bundle_id": "abcde12345",
    "created": "2015-03-04T05:03:04.292Z",
    "updated": "2015-05-16T20:39:37.508Z",
    "_class": "Insights",
    "_links": {
        "curies": [
            {
                "href": "/docs/insights/{rel}",
                "name": "insight",
                "templated": true
            }
        ],
        "insight:spoken_keywords": {
            "href": "/v1/bundles/abcde12345/insights/54321edcba"
        },
        "insight:classification": {
            "href": "/v1/bundles/abcde12345/insights/edcba56789"
        },
        "insight:spoken_words": {
            "href": "/v1/bundles/abcde12345/insights/12345abcde"
        },
        "insight:spoken_topics": {
            "href": "/v1/bundles/abcde12345/insights/34567abcde"
        },
        "insight:transcript_r4": {
            "href": "/v1/bundles/abcde12345/insights/98765abcde"
        },
        "parent": {
            "href": "/v1/bundles/abcde12345"
        },
        "self": {
            "href": "/v1/bundles/abcde12345/insights"
        }
    }
}
The most important part of this payload is the href of the insight:spoken_topics key. By retrieving the contents of that URI, Clarify will give you the topics recognized from the audio.
  • curl
curl https://api.clarify.io/v1/bundles/abcde12345/insights/34567abcde \
    --header "Authorization: Bearer myapikey" | jq '.'
# The jq portion is optional and just used to pretty print the resulting json
The final result of which is our list of topics:
{
    "id": "34567abcde",
    "bundle_id": "abcde12345",
    "name": "spoken_topics",
    "status": "ready",
    "created": "2015-11-23T22:52:37.450Z",
    "updated": "2015-11-23T22:52:37.454Z",
    "track_data": [
        {
            "track_id": "fff111",
            "track_label": "",
            "topics": [
                {
                    "categories": [
                        {
                            "path": [
                                {
                                    "name": "Sociology"
                                },
                                {
                                    "name": "Interpersonal Relationships"
                                }
                            ]
                        }
                    ],
                    "terms": [
                        {
                            "term": "life"
                        },
                        {
                            "term": "time"
                        },
                        {
                            "term": "born"
                        },
                        {
                            "term": "family"
                        },
                        {
                            "term": "father"
                        },
                        {
                            "term": "death"
                        },
                        {
                            "term": "year"
                        },
                        {
                            "term": "son"
                        },
                        {
                            "term": "man"
                        },
                        {
                            "term": "wrote"
                        },
                        {
                            "term": "mother"
                        },
                        {
                            "term": "began"
                        },
                        {
                            "term": "wife"
                        },
                        {
                            "term": "made"
                        },
                        {
                            "term": "named"
                        },
                        {
                            "term": "home"
                        },
                        {
                            "term": "young"
                        }
                    ]
                }
            ]
        }
    ],
    "_class": "SpokenTopicsInsight",
    "_links": {
        "self": {
            "href": "/v1/bundles/abcde12345/insights/34567abcde"
        },
        "curies": [
            {
                "href": "/docs/rels/{rel}",
                "name": "clarify",
                "templated": true
            }
        ],
        "parent": {
            "href": "/v1/bundles/abcde12345/insights"
        },
        "clarify:bundle": {
            "href": "/v1/bundles/abcde12345"
        }
    }
}
From here, we can process the topics just like any other json array:
  • curl
curl https://api.clarify.io/v1/bundles/abcde12345/insights/34567abcde \
    --header "Authorization: Bearer myapikey" \ | jq '.track_data[0].topics[0].categories[0].path[]'
# The jq portion is optional and just used to extract the resulting topic tree
And we end up with a list of topics that we can use to categorize or otherwise sort our content for better understanding:
{
    "name": "Humans"
}
{
    "name": "Personhood"
}
{
    "name": "Spiritualism"
}
Beta: This feature is currently in beta. Please contact Support to enable it.
Fork me on GitHub