/search

This endpoint enables to search educational ressources in various type or format (e.g. video, MOOC, training, book, etc) and from various sources (e.g. youtube, coursera, applebook, etc).

This endpoint returns a list of learning objects that matches your query, language and other optional parameters.

OpenAPI specification

The OpenAPI specification (swagger) for this endpoint is available here.

Request

GET https://api.gateway.inokufu.com/learningobject/v3/search

Headers

The API key must be included in the header.

"x-api-key": "SAY-FRIEND-AND-ENTER"

Make sure to replace SAY-FRIEND-AND-ENTER with your own Developer API key.

Query Parameters

Query parameters must be included in the URL.

Parameter	Type	Required	Description
`query`	string	Yes	This is the sentence or list of keywords that help you refine the topic of the learning objects you are looking for.
`lang`	string	Yes (default `fr`)	Language of the LO such as `en` (english) or `fr` (french).
`model`	string	Yes (default `semantic`)	The model used by the API to match your query with relevant LO. Two models are available: `semantic` or `keywords`.
`provider`	string	No	Provider (source) of the LO such as `youtube`, `coursera`, `applebooks`, etc.
`type`	string	No	Type of the LO such as `video`, `mooc`, `book`, etc.
`bloom`	string	No	List of the Bloom objectives associated with the LO such as `discover`, `understand`, `do`, etc.
`note_min`	integer [0 to 100]	Yes (default `0`)	This is an indicator of the popularity of the LO as measured by its number of likes, stars, views, etc.
`duration_unit`	string	No	The duration unit can be set as `s`(second), `min`(minute), `h`(hour), `d`(day), `w`(week), `m`(month), `y`(year).
`duration_value_min`	decimal >=0	No	The minimum duration of the LO in the `duration_unit`you have chosen.
`duration_value_max`	decimal >=0	No	The maximum duration of the LO in the `duration_unit`you have chosen.
`free`	bool	No	This allows you to filter by free content only (free=true) or paid content only (free=false). If empty, you'll get both free and paid contents.
`latitude`	decimal [-90 to 90]	No	This is the latitude of the geographical point around which you want to search for (physical) LO.
`longitude`	decimal [-180 to 180]	No	This is the longitude of the geographical point around which you want to search for (physical) LO.
`distance`	decimal >=0	No	This is the distance (in km) from the geographical point around which you want to search for (physical) LO.
`limit`	integer [1 to 25]	Yes (default `10`)	Maximum number of LO returned per page. Value must be between 1 to 25.
`page`	integer >=0	Yes (default `0`)	The number of returned page, starting at 0.

How-to

Here are some tips and advices on how-to get the best from this endpoint for the most common use cases.

How to write good query?

The query is the description of what you are looking for. By default, this query can be a natural language sentence about the topic, skill, competency or job of the learning objects you are looking for. This sentence is quite similar to the prompt you would use when interacting with ChatGPT or other LLM. However, try to be as concise and precise as possible.

For example, you can use the following queries:

learn python as a beginner
I want to learn code
how to make bread
learn to weld

How to set the language?

You can interact with this endpoint is several language. The default language is french (fr) but you can also set the language to english (en).

Use the /lang endpoint to get the full list of languages currently supported by the API. See the doc here.

How to use the `model` parameter?

The model parameter enables you to change the way your query is matched with learning objects in our index.

By default model is set to semantic. In this case, the query is matched with learning objects based on the meaning of your query (vector comparison). This is best recommended when queries are sentences in natural language.

Alternatively, model can be set to keywords. This model is required when you want to search physical learning objects (e.g. trainings) around a specific location. With this model, the query is matched with learning objects based on the presence of theses keywords in the title or description of the corresponding learning objects.

How to search from a specific source?

A common use case for this endpoint is the ability to search learning objects from a unique and specific source. For us, a source is called a provider. The provider is the host of the Learning object such as youtube, coursera, applebooks, etc.

Use the /provider endpoint to get the list of the providers currently supported by the API. See the doc here.

How to search only certain format?

A common use case for this endpoint is the ability to search learning objects of a specific format video, MOOC, book, distance learning, training, etc. You can chose the specific format you need with the parameter type.

Use the /type endpoint to get the full list of formats currently supported by the API. See the doc here.

How to search according to Bloom taxonomy?

If you need to search for learning objects that fit a specific level of objective according to the Bloom Taxonomy, you can do so using the bloom parameter. Strictly speaking, this is a simplified version of the Bloom taxonomy with mainly three levels: discover, understand and do.

Use the /bloom endpoint to get the full list of Bloom objectives currently supported by the API. See the doc here.

How to search very popular ressources?

In some case, you may want to filter the learning objects by popularity. While popularity of learning object is not always linked with its pedagogical quality, it can still be an useful indicator. For each learning object, Inokufu's Index calculate and store a normalised popularity note based on its number of likes, stars, views, etc.

If you want to filter learning object above a certain note, you can do so using the note_min parameter. This parameter enables you to set a threshold to filter out learning object below a certain popularity. This value ranges from 0 (low popularity) to 100 (exceptionally popular).

How to search ressources with a specific duration?

In some case, you may want learning objects with a specific range of duration. For example, you may not want a 40h+ marathon video about Introduction to Python but more a 5 to 10 min video. You can do so using three parameters as follows:

duration_unit: this is the duration unit. Depending the type of learning object you want, the duration can go from a second for video up to years for a training. To give you the most flexibility, you can set the unit of your choice among: s(second), min(minute), h(hour), d(day), w(week), m(month), y(year).
duration_value_min: this is the value of the minimum duration of the LO in the duration_unit you have chosen.
duration_value_max: this is the value of the maximum duration of the LO in the duration_unit you have chosen.

You can set only duration_value_min without duration_value_max if you only want to filter out learning object below a minimum duration.

You can set only duration_value_max without duration_value_min if you only want to filter out learning object above a maximum duration.

The duration_unit parameter is required when you use either duration_value_min or duration_value_max or both (in which case both values must share the same duration unit).

How to search physical ressources around a specific place?

In some case, you may want to search for learning objects which are around a specific location. For example, you may want to know what are the welder trainings within 50 km of Paris. You can do so using the four parameters as follows:

model: This MUST ce set to keywords.
distance: This is the distance (in km) from the geographical point around which you want to search for (physical) learning objects.
latitude: This is the latitude of the geographical point around which you want to search for (physical) learning objects. The value must be a decimal number between -90 and 90.
longitude: This is the longitude of the geographical point around which you want to search for (physical) learning objects. The value must be a decimal number between -180 and 180.

All these parameters need to be provided when you want to search around a specific place.

If you only have the address of a place around which you want to search, you can find the corresponding latitude and longitude using either our utility endpoint for french addresses (see here) or Google Map API (see here) for addresses outside France.

How to search free ressources only?

You can easily search for free learning ressources only using this endpoint. To do so, you have to set the free parameter to true.Alternatively, if you set the free parameter to false, you will only get paid learning ressources. If empty, you'll get both free and paid ressources.

How to search open ressources only?

In some case, you may want open educational ressources only. To do so, you have to set the license parameter to the corresponding open license of your choice. To facilitate the selection of the right license, we offer an utility endpoint /license. See the doc here.

Code example

curl "https://api.gateway.inokufu.com/learningobject/v3/search?query=python&type=mooc&lang=en"
-H "x-api-key: SAY-FRIEND-AND-ENTER"

Response

Response parameters

Parameter	Required	Description
`id`	Yes	UUID of the learning object
`title`	Yes	Title of the learning object
`url`	Yes	Link to access the learning object
`score`	No	Matching score between the learning object and the query
`description`	No	Short description of the learning object
`lang`	No	Language of the learning object
`note`	No	Note (popularity) of the learning object
`provider`	No	Provider of the learning object
`type`	No	List of the type (format) of the learning object
`bloom`	No	List of the Bloom objectives of the learning object
`picture`	No	URL to the thumbnail picture of the learning object
`duration`	No	Duration of the learning object
`address`	No	Postal address where the learning object is located (e.g. training).
`price`	No	Informations about the pricing of the learning object
`author`	No	List of authors associated with this learning object. Authors are the people that make the learning object. For mooc, distance learning or training, this can be a teacher or trainer.
`publisher`	No	List of publishers associated with this learning object. Publishers are the organisations that offer and/or sell the learning object. For mooc, distance learning or training, this can be a university, a school or a training organization.
`license`	No	URL to the license description associated to the learning object
`date`	No	Informations about the publication and last updated date of the learning object

Response example

[
    {
        "id": "6f7b1b3c-0b0q-4b0d-8b5e-9b0d7v1e9b0e",
        "title": "Python",
        "url": "https://www.python.org/",
        "score": 0.5,
        "description": "Python is a programming language",
        "lang": "fr",
        "note": 70,
        "provider": "moncompteformation",
        "type": [
            "training"
        ],
        "bloom": [
            "Cursus"
        ],
        "picture": {
            "full_width": "string",
            "square": "string"
        },
        "duration": {
            "index": 0,
            "minute": 0,
            "value": 0,
            "unit": "string"
        },
        "address": {
            "text": "string",
            "geo_coordinates": {
                "type": "string",
                "coordinates": [
                    0,
                    0
                ]
            }
        },
        "price": {
            "value": 10,
            "currency": "€",
            "free": true,
            "@context": "https://schema.org/",
            "@type": "PriceSpecification"
        },
        "author": [
            {
                "name": "string"
            }
        ],
        "publisher": [
            {
                "name": "string"
            }
        ],
        "license": {
            "url": "https://creativecommons.org/licenses/by/4.0/"
        },
        "date": {
            "publication": "string",
            "updated": "string"
        }
    }
]