Using the ViSH Search API
The ViSH Search API is a REST API for allowing cross-domain searches in a ViSH instance or node. It can be use by third-party applications to search and retrieve data of a ViSH instance. This documentation belongs to the version 1.0 of the ViSH Search API.
The ViSH Search API allows to search for different types of resources. Only the public resources are indexed by the ViSH search engine.
| Entity | type | Description |
|---|---|---|
| Resource | Resource | Search for any type of resource. This is the default type. Covers the following entities: 'Audio', 'Embed', 'Excursion', 'Flash Object', 'Link', 'Office document', 'Picture', 'SCORM Package', 'Video', 'Web application', 'Workshop', 'Writing' and 'ZIP file'. |
| Audio | Audio | Audio files. Including their conversions to HTML5 formats. |
| Embed | Embed | Embed tags or codes of external resources. |
| Excursion | Excursion | Interactive HTML5 presentations created using the ViSH Editor e-Learning authoring tool (https://github.com/ging/vish_editor). |
| Flash Object | Swf | Flash objects in SWF format. |
| Link | Link | Links to external resources. |
| Office document | Officedoc | Covers text documents (.doc, .docx, .odt), slideshows (.ppt, .pttx) and PDF files. |
| Picture | Picture | Pictures and photos. |
| SCORM Package | Scormfile | Educational contents provided as SCORM packages. |
| Video | Video | Video files. Including their conversions to HTML5 formats. |
| Web Application | Webapp | Custom web applications. |
| Workshop | Workshop | Collections of resources and activities sequenced in a specific way. |
| Writing | Writing | Paragraphs of text written using a HTML Text Editor. |
| ZIP file | Zipfile | Files in ZIP format. |
Besides resources, more entities can be searched through the ViSH Search API. Only the public information of these entities is available.
| Entity | type | Description |
|---|---|---|
| Category | Category | Collections of resources. |
| Event | Event | Scheduled events. |
| User | User | Users of the ViSH instance. |
The root URL of the ViSH Search API is /apis/search. So, for the ViSH instance http://vishub.org, the ViSH Search API is available at http://vishub.org/apis/search . Several options (or search params) are available to perform the searches.
| Param | Description | Default Value | Value example |
|---|---|---|---|
| n | Maximum number of results. The maximum value allowed for this param is 200 and the minimum 1. When pagination is active (i.e. when the search option page is present), this param specifies the number of results per page. | 20 | 100 |
| q | Keywords or search terms to perform the query. If it is not provided the search engine will return all items. | - | biology |
| id | Identifier of the entity to be retrieved. When this option is present, the rest of the search options are ignored. The API will retrieve only if present the entity with the identifier id . | - | Link:[email protected] |
| page | This option is used to perform searches with pagination. The value of page will be the page to be requested. In this case the option n will specify the results per page. The maximum number of results when using pagination is limited to 5000. | - | 1 |
| sort_by | Allows to sort the search results. If it is not provided the search engine will sort the results by relevance. The following options are available: 'ranking' (combination of popularity and quality) , 'popularity' (based on usage statistics like the visit, like or download count), 'modification' (date of modification), 'creation' (date of creation), 'visits' (frequency of visits), 'favorites' (likes received in the platform) and 'quality' (quality ratings given by users and reviewers). | - | ranking |
| type | Search only for entities of the type type (look at the previous section to see what type of entities can be searched). | Resource | Excursion,Scormfile |
| startDate | Search only for entities created after startDate. | - | 2-5-2014 |
| endDate | Search only for entities created before endDate. | - | 2-5-2014 |
| language | Search resources by language. The param language represents a language code as defined by ISO-639:1988. | - | en |
| license | Search resources by license. The param license should be one of the following license keys. | - | cc-by-nc |
| qualityThreshold | Search resources rated higher than qualityThreshold in a 0-10 scale. Non-evaluated resources have a preliminary quality score value of 5. | - | 7 |
| tags | Search resources tagged with these specific tags or keywords. | - | HTML,javascript |
| age_min | Search resources targeted for age ranges in which the higher age limit is higher than age_min. | - | 14 |
| age_max | Search resources targeted for age ranges in which the lower age limit is lower than age_max. This filter can be combined with age_min. If both filters are included, ViSH will search for resources whose age range overlaps with the [age_min,age_max] range. | - | 18 |
The root URL of the ViSH Search API is /apis/search. So, for the ViSH instance http://vishub.org, the ViSH Search API is available at http://vishub.org/apis/search . Next, some API usage examples are provided.
| Query | Description |
|---|---|
| /apis/search?q=biology&type=Excursion,Picture&n=100 | Search for Excursions and Pictures related to biology. Return the first 100 results. |
| /apis/search?q=biology&n=100&sort_by=popularity | Search the 100 most popular resources related to biology. Remember that Resource is the default type. |
| /apis/search?q=biology,chemistry,maths &type=Excursion&language=es&n=100&sort_by=creation |
Search the 100 latest Excursions created, that are in Spanish and are related to biology, chemistry or maths. |
| /apis/search?startDate=1-12-2013&endDate=31-12-2013&qualityThreshold=4 | Search for the resources created during December 2013 with a minimum quality score value of 4. Return the first 20 results. |
| /apis/search?type=User&sort_by=popularity&n=3 | Get the 3 most popular users in the ViSH instance. |
| /apis/search?id=Excursion:[email protected] | Retrieve the entity with the universal identifier "Excursion:[email protected]". If the entity is not present in the ViSH instance, it will return an empty object. |
Search results are delivered in JSON format. The delivered JSON object has several fields together with an array which contains all the results found. The following table lists all these fields:
| Field | General description |
|---|---|
| total_results | The total number of matches. |
| total_results_delivered | The total number of results delivered in the current response. |
| total_pages | Number of pages available. Only provided when pagination is active. |
| page | The index of the current page. Only provided when pagination is active. |
| results_per_page | The number of results per page. Only provided when pagination is active. |
| results | An array containing all the results found. The following section explains it in detail. |
The results field in the search results provided by the ViSH Search API is an array containing all the results found. Each result is a JSON object representing a ViSH entity. The data available for each type of entity are different. However, some fields are common to all or several entities. The following table summarizes the main fields that can be encountered in the search results.
| Field | General description | Value example | Availability |
|---|---|---|---|
| id | The global identifier of the entity. The attached example identifies the Excursion with local id 560 of the ViSH instance or node vishub.org . | Excursion:560@ vishub.org |
All entities |
| type | The type of entity. | Excursion | All entities |
| created_at | Date of creation. | 24-11-2013 | All entities |
| title | The title of the entity (the name for users). | The Higgs Particle | All entities |
| description | A description of the entity. | A brief history of Higgs particle discovery through ideas and experiments | All entities |
| tags | A list of keywords or tags of the entity. Some tags are used to catalog the resources. See the ViSH catalogue for more info. | ["Physics", "Higgs", "CERN", "LHC"] | All entities |
| url | Absolute URL to access the entity in the ViSH instance. | http://vishub.org/ excursions/560 |
All entities |
| url_full | Absolute URL to access the content of the resource. The resource can be displayed in external websites by embedding this URL via iframe. | http://vishub.org/ excursions/560.full |
Only available for resources provided in web-ready formats such as Excursions, SCORM Packages, Web Applications or Pictures among others. |
| file_url | Absolute URL to access the resource file. This URL allow to download the resource. | http://vishub.org/ excursions/560.scorm |
Only available for downloadable resources. Excursions can be downloaded in SCORM format. |
| author | The author or owner name of the entity. | Margarett Klocko | All entities but User |
| _author profile_url |
The profile URL in the ViSH instance of the author of the entity. | http://vishub.org/ users/margarett-klocko |
All entities but User |
| language | Language of the entity. It should be a language code as defined by ISO-639:1988. | en | Any entity (resource, user, ...) with a specified language. |
| license | License under which the resource was published (see licenses supported by ViSH). | "Public Domain" | All resources but Links and Embeds |
| avatar_url | An image URL to represent the entity. | http://vishub.org/ pictures/2731.jpeg |
Resources and Users. |
| visit_count | The number of visits. | 1891 | All entities but User |
| like_count | The number of likes/favorites given by the users in the ViSH instance. | 126 | All entities but User |
| download_count | The number of downloads of the resource. | 2 | All downloadable resources |
| occupation | The occupation or area of expertise of a user. | Education | User |
| loModel | Learning Object Model. Internal structure of the resource. Allows to break down the resource (Learning Object) in other Learning Objects with lower granularity. Include additional metadata as well. See ViSH Editor wiki for more info. | {JSON object} | Excursion |
| _reviewers qscore |
Rating given by reviewers in a 0-10 scale. The used quality metrics depends on the criteria and configuration of the specific ViSH instance. | 6.8 | All resources evaluated by reviewers |
| _users qscore |
Rating given by users of the ViSH instance in a 0-10 scale. The used quality metrics depends on the criteria and configuration of the specific ViSH instance. | 8.3 | All resources evaluated by users |
| start_date | Start date of a Event. | 11-02-2014 08:45 | Event |
| end_date | End date of a Event. | 11-02-2014 10:45 | Event |
| streaming | Boolean that indicates if the Event provides a streaming. | true | Event |
| embed | Embed tag to insert the streaming of an event. | <embed> ... </embed> |
Events with streaming |
| sources | Additional sources for multimedia resources. Include the conversions to HTML5 formats performed by the ViSH instance. | [{"type":"video/webm", "src":"http://vishub.org /videos/86.webm"} , {"type":"video/mp4", "src":"http://vishub.org/ videos/86.mp4"}] |
Video and Audio |
| age_range | The target age range of a resource. | 15-17 | All resources |
The ViSH platform provides a simple web application as an example of usage of the ViSH Search API. This web application consists in a HTML file with some JavaScript and CSS code. It is available on the ViSH repository at http://github.com/ging/vish/tree/master/extras/searchApp . This application allows to search on several ViSH instances using the filters and search options explained in this document using a simple UI (User Interface). To try it, just open the search.html file with a web browser. This application has been developed to orientate and help third-party applications to use the ViSH Search API.
