This tutorial will walk you through using the Squirro API. It shows first how to authenticate and then how to access any of the entities from the API.

1. Authentication

The tenant and user_id which belong to the provided authorization information are obtained during Bearer Token Creation. It is advised to take good note of these values as they are used for most API requests.

2. User Data Retrieval

All user data can be retrieved with a single request towards the Squirro API. Notice that currently user data can only be retrieved by providing an access token.

Code Block

language	python

client.get_user_data('<user_id>')

A sample JSON response is shown below.

...

language	js

...

shows how the Python SDK can be used to interface with a Squirro project.

Installation

For installation please follow the Python SDK Installation documentation. If you already have a Python environment set up, then you can install the SquirroClient package with:

Code Block
pip install SquirroClient

Gathering Information

When working with the Squirro SDK you need to provide a few pieces of information. This section explains how you can get that information.

Cluster

The cluster is the address where your Squirro has been set up. For a /wiki/spaces/BOX/overview setup this is generally http://localhost:8300 or http://box.ip.address. For the cloud version this is generally https://customer.squirro.biz or similar.

See Endpoint Mapping for additional details.

Authentication Token

For this purpose the Squirro API uses authentication tokens. To create such a token:

Open the Squirro web interface and log in as the user you'll want to use for API access.
Open the user dropdown menu on the top right, then click "API Access".
In the resulting screen under "User Token" press "Generate". The text field will then be populated with a token:
Image Added

If the text field already has a token, then simply copy that value. If you press "Renew" the current token will be invalidated and a new one is created.

Warning
Treat this token like you would your account password. The token gives full access to that account.

Project Identifier

When working with projects, for example to search items, the project's identifier is needed. The user interface provides this identifier:

Log into Squirro.
Open the Settings dropdown menu on the top right (wheelbarrow icon) and click "Project Properties".
The Project Identifier is in the resulting screen and can be copied to the clipboard.
Image Added

Instantiation & Authentication

As a first step, you need to instantiate the SquirroClient class and then authentication.

In the constructor specify the cluster, for authentication use the user authentication token.

Code Block

language	py
linenumbers	true

from squirro_client import SquirroClient

client = SquirroClient(None, None, cluster='https://next.squirro.net')
client.authenticate(refresh_token='570010…fda74e')

Searching Items

Now with a valid connection you can start searching items in an existing Squirro project. Searches are always done in the context of a project, so use the project identifier and get the most recent 15 items in a project with the following code:

Code Block

language	py
firstline	5
linenumbers	true

print client.query('l0nz…YgBg')

This will output a result like the following (output reformatted and cut to the first two items for clarity):

Code Block

language	py

{u'count': 15,
 u'eof': False,
 u'items': [{u'abstract': u'\xa0Twitter is bringing...',
             u'body': u'<html><body><img wid...',
             "en",u'created_at': u'2015-03-23T17:03:56',
           "fr"  u'external_id': u'http://techcrunch.com/?p=1135621',
        "de"     u'id': u'S8Eh_0a6SEaQwaoYtE85nQ',
    ],         "market"u'language': "en-US",u'en',
           "noise_level": 1.0,  u'link': u'http://techcrunch.com/2015/03/23/twitter-teaming-with-foursquare-for-location-tagging-in-tweets/?ncid=rss',
            "timezone": "Europe/Zurich" u'modified_at': u'2015-03-23T17:05:26',
        },     "email": "sid@squirro.com",u'objects': [{u'id': u'vXzfrgmERwy1DAMO_ZBQIw',
                "full_name": "Sid Squirro",           "id": "ug5GF9TWR26buu493Ay43w",u'project_id': u'l0nz…YgBg',
                 "known_languages": "[\"en\"]",
    "tenant": "squirro",
    "utc_offset": "3600000"
}

3. Folder & Topic Creation

After having completed that previous step a new user folder is created. Within the folder a new topic is created. It is also illustrated how folders and topics can be retrieved.

The tenant and user_id which belong to the provided authorization information are obtained during Bearer Token Creation. It is advised to take good note of these values as they are used for most API requests.

3.1. Folder Creation

After a valid access token has been received a new user folder “My Contacts” is created. The seeder for the folder is set to “my-rest-seeder”.

Code Block

language	python

client.new_folder('My Contacts', seeder='my-rest-seeder')

A sample JSON response is shown below.

Code Block

language	js

{
    "id": "-nYqTGwzRNyLK_K6RhxCeg"
}

3.2. Folder Retrieval

In a second step all available folders for the user are retrieved.

Code Block

language	python

client.get_user_folders()

A sample JSON response is shown below.

Code Block

language	js

[
    {          u'source_ids': [u'8lVtipSSTxu7q-ox1KdCjQ'],
                           u'title': u'default',
                           u'type': u'default'}],
             u'read': False,
             u'related_items': [],
             u'score': 1.0,
             u'sources': [{u'id': u'8lVtipSSTxu7q-ox1KdCjQ',
                           u'link': u'http://feeds.feedburner.com/TechCrunch',
                           u'object_ids': [u'vXzfrgmERwy1DAMO_ZBQIw'],
                "title": "My Contacts",         "topics"u'provider': 1u'feed',
        "seeder": "my-rest-seeder",                   "is_public": false,u'title': u'TechCrunch'}],
          "type": "my contacts"   u'starred': False,
        "id": "Sz7LLLbyTzy_SddblwIxaA"     }u'thumbler_url': u'd4d…f73/thumb/webshot/52/2d/18/522…5d6.png',
    {         "u'title": "My Organizations"': u'Twitter Teaming With Foursquare For Location Tagging In Tweets',
        "topics"     u'webshot_height': 22556,
          "seeder": "team"   u'webshot_url': u'http://webshot.next.squirro.net.s3-website-us-west-1.amazonaws.com/52/2d/18/522…5d6.png',
        "is_public": false,     u'webshot_width': 4884},
         "type": "my organizations"   {u'abstract': u'\xa0Instagram today ann...',
        "id": "2aEVClLRRA-vCCIvnuEAvQ"     }
]

3.3. Topic Creation

After the folder “My Contacts” has been registered a new topic “Squirro” within the folder “My Contacts” is created.

Code Block

language	python

client.new_topic(<folder_id>, 'Squirro', seeder='my-rest-seeder')

A sample JSON response is shown below.

Code Block

language	js

{
    "id": "yr9acZuKRc6YPswWm63m-Q",
    "folder_id": "-nYqTGwzRNyLK_K6RhxCeg"
}

3.4. Topic Retrieval

In a second step all available topics in a folder are retrieved.

Code Block

language	python

client.get_user_topics(folder_id=<folder_id>)

A sample JSON response is shown below.

Code Block

language	js


[
    {u'body': u'<html><body><img wid...',
             u'created_at': u'2015-03-23T17:00:43',
             u'external_id': u'http://techcrunch.com/?p=1135559',
             u'id': u'_Tt7lGnWRMKJ4b-p_zHvow',
             u'language': u'en',
             u'link': u'http://techcrunch.com/2015/03/23/instagram-layout/?ncid=rss',
             u'modified_at': u'2015-03-23T17:01:45',
              "is_ready": true,u'objects': [{u'id': u'vXzfrgmERwy1DAMO_ZBQIw',
                       "folder    u'project_id"': "Sz7LLLbyTzy_SddblwIxaA",u'l0nz…YgBg',
                           "noise_level": null,u'source_ids': [u'8lVtipSSTxu7q-ox1KdCjQ'],
              "title": "Alexander Sennhauser"             u'title': u'default',
                           u'type': u'default'}],
        "seeder": "team",     u'read': False,
           "needs_preview": false,  u'related_items': [],
            "type": "contact", u'score': 1.0,
          "id": "zFe3V-3hQlSjPtkIKpjkXg",   u'sources': [{u'id': u'8lVtipSSTxu7q-ox1KdCjQ',
            "weight": 0.0,
               u'link': u'http://feeds.feedburner.com/TechCrunch',
       "subscribed_to": true     },     {         "is_ready": true,u'object_ids': [u'vXzfrgmERwy1DAMO_ZBQIw'],
                "folder_id": "Sz7LLLbyTzy_SddblwIxaA",           u'provider': u'feed',
           "noise_level": null,                "u'title"': "Memonic"u'TechCrunch'}],
        "seeder": "my-reset-seeder"     u'starred': False,
        "needs_preview": false,     u'thumbler_url': u'260…fd9/thumb/webshot/3f/30/a7/3f3…248.jpg',
           "type": "my contacts",  u'title': u'Instagram Launches Layout, Its Own Photo Collage App',
           "id": "2sic33jZTi-ifflvQAVcfw",  u'webshot_height': 1244,
          "weight": 0.0,   u'webshot_url': u'http://webshot.next.squirro.net.s3-website-us-west-1.amazonaws.com/3f/30/a7/3f3…248.jpg',
          "subscribed_to": true
    }
]
   u'webshot_width': 1244}],
 u'next_params': {u'expected_num_results': 3402, u'start': 15},
 u'now': u'2015-03-23T18:01:06',
 u'total': 3402}

Reference

For a full documentation of the Python SDK refer to the Python SDK Reference, specifically SquirroClient, SquirroClient Entities and SquirroClient Users.

Versions Compared

Old Version 2

New Version 3

Key

1. Authentication

2. User Data Retrieval

Table of Contents

Installation

Gathering Information

Cluster

Authentication Token

Project Identifier

Instantiation & Authentication

Searching Items

3. Folder & Topic Creation

3.1. Folder Creation

3.2. Folder Retrieval

3.3. Topic Creation

3.4. Topic Retrieval

Reference

Page Comparison

Versions Compared

Old Version 2

New Version 3

Key

1. Authentication

2. User Data Retrieval

Table of Contents

Installation

Gathering Information

Cluster

Authentication Token

Project Identifier

Instantiation & Authentication

Searching Items

3. Folder & Topic Creation

3.1. Folder Creation

3.2. Folder Retrieval

3.3. Topic Creation

3.4. Topic Retrieval

Reference