The BaseSpace Search API is a set of REST service endpoints that further expand the functionality of the BaseSpace API by enabling the developer with the ability to search through the API in order to create more filtered results.
In order to use the Search API, you will need to include a valid access_token with the request.
For information about how to get Access Tokens, please view the [api-reference#OAuthProcess) documentation.
For information about how to use Access Tokens with your Search queries, please view the API Reference - Using the Access Token documentation.
More information about these processes can be found in the [/docs/content/documentation/authentication/obtaining-access-tokens) and App Triggering portions of this site.
The BaseSpace API encodes the version of the API in the resource URI. This guarantees that a given API will always behave the same, even if we introduce newer APIs. Example:
/v1pre3/search
This path refers to API version v1pre3.
For requests returning collections, these query parameters are common:
Offset: The starting point of the collection to read, there is no maximum value for Offset. Default: 0
Limit: The maximum number of items to return. This value may be less than requested if the request size was reduced by the server. Default: 10, Range: 0-1024, the implicit Range of Limit for the Files resource is 0-1000.
SortDir: The way to sort the resulting collection, either ascending or descending. Default: 'Asc', Can be 'Asc' or 'Desc'
SortBy: The field to use to sort the resulting collection. This value can have multiple possibilities depending on the result type
The response will also contain these fields unless noted otherwise:
DisplayedCount: The number of items returnedTotalCount: The total number of items in the collectionThese are included for all response types. In addition to Resource Collection Requests if applicable.
Response - The main response object
Items: If a list is returned, it is contained within this response elementId: Id of the resourceName: Name of the selected resourceHref: Location of the resource in the APIDateCreated: When this resource was createdUserOwnedBy: Information about the User who owns this resourceStatus: The status of the resource, if it is inside of an appsession it is the status of the AppSessionHrefBaseSpaceUI: The location of this resource in the BaseSpace User InterfaceProperties: The Properties of this resource. Some Properties are standard in BaseSpace and some are custom Properties created by Users or Apps.ResponseStatus - Empty for responses with a 200 response code. For error cases, contains human-readable description of the error. The documentation on the error cases is not yet complete.
Notifications - An array of notifications. Documentation on this element is not complete.
BROWSE GLOBAL access (requires access token)x-access-token: The access_token that has browse global level of permission to the user's datascope: The scope that you wish to have applied to the search query, possible values are sample_files, appresult_files, appresults, samples, runs, genomes, and projectsquery: A query that you wish to apply to the search query, this is to further narrow the search results. There is a table below which shows all possible queries for the different resources above.This section describes the possible values for query when using the Search API.
| Resource (`scope` value) | Possible values for `query` |
runs |
href, name, number, experimentname, reagentbarcode, flowcellbarcode, bufferbarcode, totalsize, hreffiles, hrefsamples, status, userownedby, instrument, instrumentname, instrumenttype, numcyclesread1, numcyclesread2, numcyclesindex1, numcyclesindex2 |
projects |
namedescriptionuserownedby |
genomes |
namebuilddisplaynamespeciesnamespecies |
samples |
namecustomidsamplenumberrootfoldersampleidprojectnameexperimentnameindexsequenceindexsequence2ispairedendread1read2numreadsrawnumreadspfismergedtotalsizestatusstatussummaryuserownedbygenomesampleappsessionrootappsessionprojectsproperty |
appresults |
namedescriptiontotalsizeuserownedbygenomesampleappappsessionrootappsessionprojectsproperty |
sample_files |
userownedbygenomesampleappappsessionrootappsessionprojectsfileextensionsize |
appresult_files |
userownedbygenomeappresultappappsessionrootappsessionprojectsfileextensionsize |
Each of these queryable items are objects, so in the query string you will have to go through the JSON for these resources and specify the value you would like to query, e.g. to search for a Project with a certain Name or Id you would type (projects.name:<projectname>) and (projects.id:<projectid>) respectively. The information available for each resource is available in the BaseSpace API Reference documentation.
For questions about the query syntax or for more advanced queries, please view the following page: http://lucene.apache.org/core/294/queryparsersyntax.html. This is the Query syntax for elastic search queries.
Some examples of search queries in BaseSpace.
Search for a resource by name, in this example we are searching for a Run with 140609 in its name:
http://api.basespace.illumina.com/v1pre3/search?scope=runs&access_token={access_token}&query=(name:%22140609%22)
Search for all Samples in Project with Id 2:
http://api.basespace.illumina.com/v1pre3/search?scope=samples&access_token={access_token}&query=(project.Id:2)
Search for all Samples in Project with Id 4 and for which the Genome is hg19:
http://api.basespace.illumina.com/v1pre3/search?scope=samples&access_token={access token}&query=((genome.build:hg19)%20AND%20(project.id:4))