Searching with Gooru API

How to use Gooru's Search API

There are 2 steps to sending a request:

  1. Signing in and obtaining an access token
  2. The actual search request (which uses the received access token)

Signing in

Here is an example of an request that you can try out to sign in (it will not work because you need to change the "Authorization header").

POST /api/nucleus-auth/v1/token HTTP/1.1
Host: gooru.org
Authorization: Basic c3pnb29ydTpnb28ydTEyMw==
Content-Type: application/json
Cache-Control: no-cache

{"client_key" : "c2hlZWJhbkBnb293dWxlYXJuaW5nLm8yZw==", 
"client_id" : "ba956a87-ae15-11e6-a302-f8a963065976", 
"grant_type" : "credential"}

📘

Encoding username and password

The string that goes after "Basic" in the authorization header must be substituted by a gooru username and password in the following format using base64 encoding:

encode(username:password)

For example, username: john, password: 12345, encodes to:

encode64(john:12345) = "am9objoxMjM0NQ=="

So your final Authorization header will look like this:

Authorization: Basic am9objoxMjM0NQ==

This request will return a json containing an "access_token" which will be used to perform the actual search request.

Here is a sample response that would be received after successfully signing in. Please pay special attention to the "access_token" as it will be needed for running subsequent requests.

{
  "user_id": "a0273f89-95fc-440b-8a0c-47255a6c7272",
  "username": "dlama",
  "client_id": "ba953a97-ae15-11e5-a302-f0a963065976",
  "provided_at": 1466592075495,
  "prefs": {
    "email_id": "[email protected]"
  },
  "cdn_urls": {
    "user_cdn_url": "//usercdn.gooru.org/",
    "content_cdn_url": "//cdn.gooru.org/"
  },
  "access_token": "MTQ2NjU5MjA3NTQ5NTphMDI3M2Y2OS05NWZjLTQ0MGItOGEwYy00NzI1NWE2YzcyNzI6YmE5NTZhOTctYWUxNS0xMWU1LWEzMDItZjhhOTYzMDY0OTc2",
  "firstname": "Dalai",
  "lastname": "Lama",
  "user_category": "student"
}

The Search Request

The search request syntax will not vary much and the same query parameters you are currently using should work:

GET /gooru-search/rest/v2/search/resource?pageNumber=1&pageSize=5&q=solar HTTP/1.1
Host: gooru.org
Authorization: Token MTQ2NjU5MjA3NTQ5NTxhMDI3M2Y3OS05NWZjLTQ0MGItOGEwYy00NzI1NWE2YzcyNzI6YmE5NTZhOTctYWUxNS0xMWU1LWEzMDItZjhhOTYzMDY1OTc2
Content-Type: application/json
Cache-Control: no-cache

Which should return a JSON in the following format:

{
  "executionTime": 17,
  "query": {
    "rewrittenQueryString": "solar",
    "userQueryString": "solar"
  },
  "resultCount": 8,
  "searchCount": 0,
  "searchResults": [
    {
      "addDate": 1320025140000,
      "aggregator": null,
      "assetURI": null,
      "brokenStatus": 0,
      "collaboratorCount": null,
      "collectionCount": 10,
      "contentFormat": "resource",
      "contentId": null,
      "contentPermissions": null,
      "contentSubFormat": "video_resource",
      "course": null,
      "creator": {
        "emailId": "",
        "firstName": "Rocky",
        "gooruUId": "ee410cef-2a44-46ef-878d-172511e54e07",
        "isDeleted": false,
        "lastName": "Shore",
        "organizationName": null,
        "partyUid": "ee410cef-2a44-46ef-878d-172511e54e07",
        "profileImageUrl": null,
        "userRoleSetString": null,
        "username": "Rocky",
        "usernameDisplay": "Rocky"
      },
      "customFields": {
        "importMode": "Update",
        "endUser": "Student",
        "scriptCode": "latn",
        "size": "Colossal Squid",
        "domain": {
          "name": "video.nationalgeographic.com",
          "attribution": "National Geographic",
          "url": "http:\/\/video.nationalgeographic.com"
        },
        "dataType": "MP4",
        "publisher": [
          "National Geographic"
        ],
        "mobileFriendliness": "iPad_friendly",
        "language": "eng",
        "accessMode": [
          "Visual"
        ],
        "learningMode": "Expositive"
      },
      "depthOfKnowledges": null,
      "description": "Students will learn about solar power in this video.",
      "distinguish": 0,
      "educationalUse": null,
      "entryId": null,
      "folder": null,
      "gooruOid": "925611ee-ed47-4c73-8ad6-78d1c057c675",
      "grade": null,
      "hasFrameBreaker": false,
      "indexId": null,
      "instructional": null,
      "isDeleted": 0,
      "isOer": 0,
      "lastModified": 1402982788000,
      "lastModifiedString": "2014-06-17T05:26:28Z",
      "libraryNames": null,
      "license": {
        "code": "Not Available",
        "icon": null,
        "name": "non-exclusive license",
        "url": "http:\/\/creative.common.org"
      },
      "momentsOfLearning": null,
      "publishStatus": "published",
      "publisher": [
        "National Geographic"
      ],
      "ratings": {
        "average": 0,
        "reviewCount": 0,
        "count": 0
      },
      "recordSource": null,
      "resourceAddedCount": 10,
      "resourceFormat": {
        "value": "Video"
      },
      "resourceSource": {
        "frameBreaker": false,
        "resourceSourceId": 0,
        "activeStatus": 0,
        "domainName": "video.nationalgeographic.com",
        "attribution": "National Geographic",
        "sourceName": null,
        "type": null,
        "url": "http:\/\/video.nationalgeographic.com"
      },
      "resourceTags": null,
      "resourceType": null,
      "resourceUsedUserCount": 0,
      "resultUId": "2febd9d4-b786-4591-a5fe-b7458e9e2880",
      "s3UploadFlag": 0,
      "scollectionIds": "8bd94bd7-460f-4e49-9a32-ce9dd8c24eef || 2ea93031-65cb-4c93-ac2c-b16a9a6fdd88 || 33c2e2f9-107c-49e3-87f9-480456097c2f || cb455aa5-0371-471e-b63b-a2514b704ded || 60b15b12-b58f-4cdf-a931-a60c6b790b33 || 538f9e83-3ef1-411e-bc55-c819b3ec3690 || 49d7552b-5696-4ecc-bc48-e46eea0f6a18 || 7b498b07-7183-4138-a66c-22baffa3bf4d || 5179547d-09d5-42f8-9555-ac04bde5fab2 || 7a9d57eb-e816-4145-891d-61031a405f6d",
      "scollectionTitles": "Energy Transport || Environmental Science || Solar Energy || Solar Power  || Solar and Nuclear Energy (Warr) || Solar Power",
      "sharing": "public",
      "taxonomyDataSet": "{\"subject\":[],\"course\":[],\"domain\":[],\"curriculum\":{\"curriculumCode\":[],\"curriculumDesc\":[],\"curriculumName\":[],\"curriculumInfo\":[]}}",
      "taxonomySet": {
        "subject": [
          
        ],
        "domain": [
          
        ],
        "course": [
          
        ],
        "curriculum": {
          "curriculumName": [
            
          ],
          "curriculumCode": [
            
          ],
          "curriculumInfo": [
            
          ],
          "curriculumDesc": [
            
          ]
        }
      },
      "thumbnail": "0005\/2674\/925611ee-ed47-4c73-8ad6-78d1c057c675.png",
      "thumbnails": null,
      "title": "Solar Power",
      "url": "http:\/\/video.nationalgeographic.com\/video\/player\/environment\/energy-environment\/solar-power.html",
      "user": {
        "emailId": "",
        "firstName": "Rocky",
        "gooruUId": "ee410cef-2a44-46ef-878d-172511e54e07",
        "isDeleted": false,
        "lastName": "Shore",
        "organizationName": null,
        "partyUid": "ee410cef-2a44-46ef-878d-172511e54e07",
        "profileImageUrl": null,
        "userRoleSetString": null,
        "username": "Rocky",
        "usernameDisplay": "Rocky"
      },
      "viewCount": 0,
      "views": 0
    }
  ],
  "stats": {
    "pageSize": 8,
    "totalHitCount": 2077,
    "pageNumber": null
  },
  "totalHitCount": 2077
}

Input Parameters & Request Syntax

Gooru Search Syntax should follow this example:

{REST_END_POINT}/gooru-search/rest/v2/search/{type}?pageNum={pageNum}&pageSize={pageSize}&q={search term}

NameData TypeParam TypeDefault ValueOptional?Allowed Values
pageSizeIntegerRequest Param8YesOnly Integer values 1 to 20
startAtIntegerRequest Param0YesOnly Integer values
pageNumIntegerRequest Param1YesOnly Integer values
qStringRequest ParamNilNoNumbers , String, Logical expression(i.e query1 OR query2),Prefix filter query (i.e water:video, ocean:webpage)

Note: The query term should be meaningful and must contain more than 3 characters
Gooru-Session-TokenStringRequest HeaderNilNoSession Token obtained from Gooru Core Authentication API.
typeStringPathVariableNilNoOnly “resource,scollection” values supported.

Resource refers to an individual resource, while scollection refers to a collection of resource.