With thousands of learning content in the Go1 library - it's important to build a content search and discovery process that will enable end-users to find the content they need as quickly and as easily as possible.
To assist users in discovering the most relevant content, we recommend implementing our content filters, using the learning-objects API endpoint. In this document, we'll introduce each of our filters, and provide implementation instructions for you to follow.
This document will cover the following filters:
- Sort
- Topics
- Providers
- Language
- Duration
Sort filter
The sort filter allows users to specify the order in which the set of content they are searching for will be returned. For example, you can sort the returned content by the most popular, the most relevant or in alphabetical order. Implementing a default sort preference and allowing users to select their own sorting preference is essential for providing users with the best content search and discovery process when using the Go1 API.
To apply the filter, the sort query parameter should be passed when making a GET request to the /v2/learning-objects API endpoint.
There are 4 primary sort options available:
- title - sorts results in alphabetical order based on the learning object title
- relevance - when searching by keyword, sorts results based on our relevance algorithm
- popularity - sorts results based on the most used content
- created - sort results by creation date
When making a 'search' request by passing a keyword to /v2/learning-objects, we recommend setting the sort parameter to relevance. This will return the most relevant search results, and allow for the best end-user experience.
Here is an example request:
curl --request GET \ --url https://api.go1.com/v2/learning-objects?keyword=leadership&sort=relevance
Additionally, we recommend building your interface to allow end-users to select their own sort preferences. Refer to the screenshot at the top of this section for an example.
You can also specify the sorting direction - eg:
- sort=created:desc will sort by creation date, showing the most recent objects first.
- sort=created:asc will sort by creation date, showing the oldest created objects first.
Refer to the API Reference for more detail on structuring your API call to /v2/learning-objects.
Topics filter
The topics filter allows users to narrow their search to a particular subject matter, skill or learning category within the Go1 library.
Building the topics filter using the API is a two-step process.
- You'll need to know the list of available Go1 topics — you can make a request to the API to retrieve this list.
- Once you know the list of available topics, you can retrieve content from a selected topic, by including the topics[] parameter in your GET request to /v2/learning-objects, and passing in the specific topic of choice.
We'll walk through both of these steps in greater detail below.
Step 1: Retrieve a list of topics
To retrieve a list of available topics, make a GET request to /v2/learning-objects and include the following query parameters:
- facets=topics, the facets parameter can be used to retrieve a list of available languages, tags, content groups, providers (aka instance) and topics. In this scenario, we'll request a list of topics.
- limit=0, the limit parameter is used to specify the number of learning objects returned when making a request to /v2/learning-objects. When limit is not specified, the learning-objects endpoint will always return a default of 20 LO's. Since we only want a list of topics, set limit to 0, thus removing any learning objects from the response.
Here is an example request:
curl --request GET \ --url https://api.go1.com/v2/learning-objects?limit=0&facets=topics
Example response - note, we have removed most of the available topics in the below example to keep the response short:
{
"total": 74665,
"hits": [],
"facets": {
"instance": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{{A LIST OF PROVIDERS WILL BE DISPLAYED HERE}}
]
},
"topics": { // the object containing all of the available topics
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": "Technology Skills", // the topic name
"doc_count": 41559 // number of content in this topic
},
{
"key": "Business Skills",
"doc_count": 19165
}
]
},
"tag": {
"buckets": []
},
"collection_id": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": 0,
"doc_count": 0
}
]
}
}
}You'll notice that the response message includes a "topics" object in the JSON construct. This topics object will include a list of all available topics in the Go1 library. You'll use these topics in the next step.
Step 2: Request a list of content within a selected topic
With the list of topics returned in step 1, you are now ready to construct a request to the API to return a list of content from a selected topic. This is done by making a GET request to /v2/learning-objects, and by including the topics[] parameter to pass in the selected topic.
Here is an example request:
curl --request GET \ --url https://api.go1.com/v2/learning-objects?topics[]=Technology Skills
The response will include a list of learning objects from the 'Technology Skills' topic.
Note, you can combine the above method with the keyword parameter to return a keyword search for content within that particular topic. Refer to the API Reference for more detail on structuring your API call to /v2/learning-objects.
Provider filter
Providers represent the 'authors' or 'creators' of the Go1 learning content. We currently work with over 100 different content providers around the world, each with its unique learning modalities, style and delivery methods. Filtering by providers will allow end-users the ability to more easily segment and discover content from their preferred creators.
Building the providers filter using the API is a two-step process.
- You'll need to know the list of Go1 providers, specifically the provider ID's — you can make a request to the API to retrieve this list.
- Once you know the list of provider ID's, you can retrieve content from a selected provider, by including the provider parameter in your GET request to /v2/learning-objects, and passing in the provider's ID.
We'll walk through both of these steps in greater detail below.
Step 1: Retrieve a list of providers (provider ID's)
To retrieve a list of providers and their associated ID's, make a GET request to /v2/learning-objects and include the following query parameters:
- facets=instance, the facets parameter can be used to retrieve a list of available languages, tags, content groups, providers (aka instance) and topics. In this scenario, we'll request a list of providers. This is done by passing in 'instance'.
- limit=0, the limit parameter is used to specify the number of learning objects returned when making a request to /v2/learning-objects. When limit is not specified, the learning-objects endpoint will always return a default of 20 LO's. Since we only want a list of providers, set limit to 0, thus removing any learning objects from the response.
Here is an example request:
curl --request GET \ --url https://api.go1.com/v2/learning-objects?limit=0&facets=instance
Example response, note - we have removed the majority of providers in this example to keep the response short:
{
"total": 74666,
"hits": [],
"facets": {
"instance": { // this is the object containing all of the providers
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": 4878185, // this is the provider ID
"doc_count": 28004, // number of content the provider has
"name": "CreativeLive" // the providers name
},
{
"key": 3988776,
"doc_count": 7438,
"name": "BizLibrary"
}
]
},
"tag": {
"buckets": []
},
"collection_id": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": 0,
"doc_count": 0
}
]
}
}
}You'll notice that the response message includes an "instance" object in the JSON construct. This instance object will include a list of all available providers in the Go1 library. The "key" value is the provider ID, which will be used to return a list of content from a specific provider in the next step.
Step 2: Request a list of content from a selected provider
With the list of provider ID's returned in step 1, you are now ready to construct a request to the API to return a list of content from a selected provider. This is done by making a GET request to /v2/learning-objects, including the providers parameter to pass in the selected provider ID.
Here is an example request:
curl --request GET \ --url https://api.go1.com/v2/learning-objects?providers=3988776
The response will include a list of learning objects from the provider you have specified, in this instance the provider '3988776' which is BizLibrary.
Note, you can combine the above method with the keyword parameter to return a keyword search for content within that particular topic. Refer to the API Reference for more detail on structuring your API call to /v2/learning-objects.
Language filter
The Go1 library has content available across a range of various languages. The language filter allows users to filter their content searches to find content from a specific language of their choice.
Building the language filter using the API is a two-step process.
- You'll need to know the list of languages available — you can make a request to the API to retrieve this list.
- Once you know the list of available languages, you can retrieve content in a selected language, by including the language parameter in your GET request to /v2/learning-objects.
We'll walk through both of these steps in greater detail below.
Step 1: Retrieve a list of available languages
To retrieve a list of available languages, make a GET request to /v2/learning-objects and include the following query parameters:
- facets=language, the facets parameter can be used to retrieve a list of available languages, tags, content groups, providers (aka instance) and topics. In this scenario, we'll request a list of languages.
- limit=0, the limit parameter is used to specify the number of learning objects returned when making a request to /v2/learning-objects. When limit is not specified, the learning-objects endpoint will always return a default of 20 LO's. Since we only want a list of languages, set limit to 0, thus removing any learning objects from the response.
Here is an example request:
curl --request GET \ --url https://api.go1.com/v2/learning-objects?limit=0&facets=language
Example response - note, we have removed the majority of languages in this example to keep the response short:
{
"total": 74665,
"hits": [],
"facets": {
"instance": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{{A LIST OF PROVIDERS WILL BE DISPLAYED HERE}}
]
},
"language": { // object containing the list of languages
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": "en", // this is the language
"doc_count": 72620 // number of content available
},
{
"key": "es",
"doc_count": 1111
}
]
},
"tag": {
"buckets": []
},
"collection_id": {
"doc_count_error_upper_bound": 0,
"sum_other_doc_count": 0,
"buckets": [
{
"key": 0,
"doc_count": 0
}
]
}
}
}You'll notice that the response message includes a "language" object in the JSON construct. This language object will include a list of all available languages in the Go1 library. The "key" value is the language in lower-case two-letter ISO 639-1 codes. You'll use these key values to return content from selected languages in step 2 below.
Step 2: Request a list of content from a selected language
With the list of languages returned in step 1, you are now ready to construct a request to the API to return a list of content from a selected language. This is done by making a GET request to /v2/learning-objects, including the language[] parameter to pass in the selected language key value in lower-case two-letter ISO 639-1 codes.
Here is an example request:
curl --request GET \ --url https://api.go1.com/v2/learning-objects?language[]=es
The response will include a list of learning objects in the language you have specified, in this instance the language 'es' which is Español (Spanish).
Note, you can combine the above method with the keyword parameter to return a keyword search for content within that particular topic. Refer to the API Reference for more detail on structuring your API call to /v2/learning-objects.
Duration filter
The duration filter allows users to find content that is within a specified duration. There are two query parameters required to filter by duration:
- duration[min] - Filter by minimum duration in minutes. Will return learning objects with the specified duration or longer.
- duration[max] - Filter by maximum duration in minutes. Will return learning objects with the specified duration or shorter.
An example request filtered by duration may look like the below, where a user wishes to find a 'Project Management' course that is less than 30 minutes long:
curl --request GET \ --url https://api.go1.com/v2/learning-objects?limit=20&keyword=Project Management&duration[min]=0&duration[max]=30
If the user would like to extend the duration range to courses between 30 to 60 minutes, the request might look like the following:
curl --request GET \ --url https://api.go1.com/v2/learning-objects?limit=20&keyword=Project Management&duration[min]=30&duration[max]=60
There is also support for multiple duration ranges. A request with multiple duration ranges would look like the following: duration[0][min]=0&duration[0][max]=15&duration[1][min]=60.
Note, you can combine the above method of filtering by duration with the keyword parameter to return a keyword search for content within a particular duration band. Refer to the API Reference for more detail on structuring your API call to /v2/learning-objects.