{{warning}}

Search

Using the search API requires two pieces of information:

  1. A CoreSpring access token.
  2. A JSON object representing the criteria of the search to perform.

An example of a simple JSON object containing a simple textual search is as follows:

  {
    "text": "fractions"
  }

The JSON object must also be URI encoded:

%7B%22text%22%3A%22fractions%22%7D

Add the URI encoded JSON object and the the API token as query parameters to the URI:

https://platform.corespring.org/api/v2/items?access_token=[token]&query=%7B%22text%22%3A%22fractions%22%7D

A JavaScript function to generate a search URI would look something like this:

function toSearchURL(token, searchObject) {
  return encodeURI('https://platform.corespring.org/api/v2/items?access_token=' +
    token + '&query=' + JSON.stringify(searchObject));
}

The above example is intended as a server-side example; keep in mind that it may be beneficial to be restrictive with regard to sending an access_token to the client.

Using the curl command this could be passed as a GET request:

curl http://localhost:9000/api/v2/items\?access_token\=8iqmd48jg3go54x057tuq8v4h\&query\=%7B%22text%22%3A%22fractions%22%7D
{
  "total" : 10,
  "hits" : [ {
    "id" : "12345:0",
    "collectionId" : "532258c5827533a417427f71",
    "published" : true,
    "standards" : [ "5.NF.A.1" ],
    "subject" : "Mathematics",
    "gradeLevels" : [ "05" ],
    "title" : "Add and subtract mixed numbers with unlike denominators.",
    "interactionCount" : 1
  },
  ...
  ]
}

Search Mode

There are 2 possible search modes: latest and latestPublished.

{
  //optional - defaults to "latest"
  "mode" :  "latestPublished",
  //...
}
  • latest searches for the latest version of an item. This is the default mode.
  • latestPublished searches for the latest version of an item where published: true.

Example

Imagine you have an item with 2 versions: 1:0 and 1:1. 1:1 is the latest version but is unpublished. 1:0 is the penultimate version but is published. Searching using mode: latest will only ever find 1:1. Searching using mode: latestPublished will only ever find 1:0.

Pagination

Pagination is achieved using the offset and count keys in the query object:

{
  "offset" : 0,
  "count" : 50,
  "text" : "fractions"
}

The default values of offset and count are 0 and 50 respectively. If the hits field in the JSON result exceeds the count value specified, it means that there were more results available than were returned and the offset must be increased to see the additional results. For example, if there were 150 available results, send the following to catch up:

{
  "offset" : 50,
  "count" : 50,
  "text" : "fractions"
}

and then

{
  "offset" : 100,
  "count" : 50,
  "text" : "fractions"
}

to see all the results.

Sorting

Sort search results by providing a "sort" attribute in the JSON model. The "sort" attribute's value is an object whose key is the field to sort, and whose value is either "asc" or "desc" For example, the following JSON object

{
  "sort" : {
    "title" : "asc"
  }
}

would filter by the title field of the results, in ascending order. If neither "asc" or "desc" is specified "asc" will be used by default.

Filtering

Queries can be filtered using the contributors, collections, itemTypes, gradeLevels and published fields.

Contributors

The contributors field enables filtering by the organizations associated with the item. For example:

{
  "contributors" : ["MA DESE"]
}

To filter by specific contributors make a call to the v1 contributors api endpoint:

https://platform.corespring.org/api/v2/contributors?access_token=[access token]

Collections

To filter by collections:

{
  "collections" : ["502404dd0364dc35bb393398"]
}

Note that the collections attribute of the JSON object contains a list of the collection ids for filtering, and not the names of the collections. Obtain a list of the collection name/id values from the following endpoint:

https://platform.corespring.org/api/v2/collections?access_token=[access token]

Item Type

Items or question contain interaction types such as multiple choice or ordering. To filter by interaction type use the itemTypes attribute:

{
  "itemTypes" : ["corespring-multiple-choice"]
}

To obtain a list of available item types from the following URL:

https://platform.corespring.org/api/v2/item-types?access_token=[access token]

The values used to filter by type are in the "key" field of these results. The "value" is the human-readable name for the item type.

Grade Levels

Filter the returned items by grade level using the gradeLevels attribute:

{
  "gradeLevels" : ["09", "10", "11", "12"]
}

The values available for grade level may be obtained from the following URL:

https://platform.corespring.org/api/v2/grade-levels?access_token=[access token]

Note that grade levels are String values padded with a leading zero, and not Number values.

Published

The published boolean attribute is used to filter those items which have been designated as "published" by the content author or [organization] (collections).

{
  "published" : true
}

Interaction Count

The interactionCount integer defines the number of interactive components included within the item. For example, if an item contained two multiple choice interactions and an open ended answer interaction, the interactionCount property would be equal to 3.

{
  "interactionCount" : 2
}

Advanced Example

Suppose you wanted to search for all items matching the text "fractions" in the CoreSpring's Open Math collection that had been published. The following JSON query would achieve this:

{
  "text" : "fractions",
  "collections": ["502404dd0364dc35bb393398"],
  "published" : true,
}

Once URI encoded, the JSON object should look as follows:

%7B%0A%20%20%22text%22%20%3A%20%22fractions%22%2C%0A%20%20%22collections%22%3A%20%5B%22502404dd0364dc35bb393398%22%5D%2C%0A%20%20%22published%22%20%3A%20true%2C%0A%20%20%22workflows%22%20%3A%20%5B%22qaReview%22%5D%0A%7D

Added as the query parameter, with the API access token, the full URL is as follows:

https://platform.corespring.org/api/v2/items?access_token=[access token]&query=%7B%0A%20%20%22text%22%20%3A%20%22fractions%22%2C%0A%20%20%22collections%22%3A%20%5B%22502404dd0364dc35bb393398%22%5D%2C%0A%20%20%22published%22%20%3A%20true%2C%0A%20%20%22workflows%22%20%3A%20%5B%22qaReview%22%5D%0A%7D