---
agentTools:
projectIndex: https://docs.cancergenomicscloud.org/llms.txt
---
# ↳Search via the Datasets API
QUERY DATASETS > About the Datasets API > Search via the Datasets API
[block:callout]
{
"type": "warning",
"title": "On this page:",
"body": "* [Overview](#section-overview)\n* [Search by term](#section-search-by-term)\n * [Path](#term-path)\n * [Header fields](#term-header-fields))\n * [Query parameters](#term-query-parameters)\n * [Example request](#term-example-request)\n * [Example response](#term-example-response)\n* [Search by URI](#section-search-by-uri)\n * [Path](#uri-path)\n * [Header fields](#uri-header-fields)\n * [Query parameters](#uri-query-parameters)\n * [Example request](#uri-example-request)\n * [Example response](#uri-example-response)"
}
[/block]
\##Overview
Search through datasets using the Datasets API by issuing `GET` requests. On this page, we'll introduce the structure of two types of search requests: [search by term](#section-search-by-term) and [search by Unique Resource Identifier (URI)](#section-search-by-uri). First, search by term to find all exact matches for your free-text search across all databases. Then, use the URIs obtained in the initial search to obtain further details, including individual members matching the designated resource.
\##Search by term
This is a free-text search by term for exact matches in the metadata across all databases. Use search terms fro metadata for this request. Learn more about [metadata for datasets](https://docs.cancergenomicscloud.org/docs/about-metadata-for-datasets).
\###Path
[block:code]
{
"codes": [
{
"code": "http://cgc-datasets-api.sbgenomics.com/search",
"language": "text",
"name": "Path"
}
]
}
[/block]
\###Header fields
[block:parameters]
{
"data": {
"0-0": "`X-SBG-Auth-Token`\nrequired",
"h-0": "Name",
"h-1": "Description",
"0-1": "Your CGC [authentication token](https://docs.cancergenomicscloud.org/docs/get-your-authentication-token)"
},
"cols": 2,
"rows": 1
}
[/block]
\###Query parameters
[block:parameters]
{
"data": {
"0-2": "Data matching this search `term` will be returned. Note that the `term` must be an exact complete string for the results to match.",
"0-0": "`term`",
"h-0": "Name",
"h-1": "Datatype",
"h-2": "Description",
"0-1": "string"
},
"cols": 3,
"rows": 1
}
[/block]
\###Example request
[block:code]
{
"codes": [
{
"code": "GET /search?term=brca HTTP/1.1\nHost: cgc-datasets-api.sbgenomics.com\nX-SBG-Auth-Token: 3210a98c1db9304ea9d9273156740f74",
"language": "http",
"name": "Example request"
}
]
}
[/block]
\###Example response
This will return a list of results from datasets accessible through the CGC, grouped by the dataset to which they belong, as shown below.
[block:code]
{
"codes": [
{
"code": "{\n \"tcga\": [\n {\n \"type\": \"http://www.w3.org/2002/07/owl#NamedIndividual\",\n \"label\": \"BRCA\",\n \"uri\": \"https://www.sbgenomics.com/tcga/disease_type/brca\"\n },\n {\n \"type\": \"https://www.sbgenomics.com/ontologies/2014/11/tcga#Utility\",\n \"label\": \"BRCA\",\n \"uri\": \"https://www.sbgenomics.com/tcga/disease_type/brca\"\n },\n {\n \"type\": \"http://www.w3.org/2000/01/rdf-schema#Resource\",\n \"label\": \"BRCA\",\n \"uri\": \"https://www.sbgenomics.com/tcga/disease_type/brca\"\n },\n {\n \"type\": \"https://www.sbgenomics.com/ontologies/2014/11/tcga#Diagnosis\",\n \"label\": \"BRCA\",\n \"uri\": \"https://www.sbgenomics.com/tcga/disease_type/brca\"\n },\n {\n \"type\": \"https://www.sbgenomics.com/ontologies/2014/11/tcga#DiseaseType\",\n \"label\": \"BRCA\",\n \"uri\": \"https://www.sbgenomics.com/tcga/disease_type/brca\"\n },\n {\n \"type\": \"http://www.w3.org/2002/07/owl#NamedIndividual\",\n \"label\": \"TCGA-BRCA\",\n \"uri\": \"https://www.sbgenomics.com/tcga/investigation/tcga-brca\"\n },\n {\n \"type\": \"https://www.sbgenomics.com/ontologies/2014/11/tcga#Utility\",\n \"label\": \"TCGA-BRCA\",\n \"uri\": \"https://www.sbgenomics.com/tcga/investigation/tcga-brca\"\n },\n {\n \"type\": \"http://www.w3.org/2000/01/rdf-schema#Resource\",\n \"label\": \"TCGA-BRCA\",\n \"uri\": \"https://www.sbgenomics.com/tcga/investigation/tcga-brca\"\n },\n {\n \"type\": \"https://www.sbgenomics.com/ontologies/2014/11/tcga#Investigation\",\n \"label\": \"TCGA-BRCA\",\n \"uri\": \"https://www.sbgenomics.com/tcga/investigation/tcga-brca\"\n }\n ],\n \"ccle\": [\n {\n \"type\": \"http://www.w3.org/2002/07/owl#NamedIndividual\",\n \"label\": \"BRCA\",\n \"uri\": \"https://www.sbgenomics.com/ccle/disease_type_abbr/03\"\n },\n {\n \"type\": \"https://www.sbgenomics.com/ontologies/2016/5/ccle#Clinical\",\n \"label\": \"BRCA\",\n \"uri\": \"https://www.sbgenomics.com/ccle/disease_type_abbr/03\"\n },\n {\n \"type\": \"https://www.sbgenomics.com/ontologies/2016/5/ccle#DiseaseTypeAbbreviation\",\n \"label\": \"BRCA\",\n \"uri\": \"https://www.sbgenomics.com/ccle/disease_type_abbr/03\"\n },\n {\n \"type\": \"https://www.sbgenomics.com/ontologies/2016/5/ccle#Utility\",\n \"label\": \"BRCA\",\n \"uri\": \"https://www.sbgenomics.com/ccle/disease_type_abbr/03\"\n },\n {\n \"type\": \"http://www.w3.org/2000/01/rdf-schema#Resource\",\n \"label\": \"BRCA\",\n \"uri\": \"https://www.sbgenomics.com/ccle/disease_type_abbr/03\"\n },\n {\n \"type\": \"http://www.w3.org/2002/07/owl#NamedIndividual\",\n \"label\": \"CCLE-BRCA\",\n \"uri\": \"https://www.sbgenomics.com/ccle/investigation/03\"\n },\n {\n \"type\": \"https://www.sbgenomics.com/ontologies/2016/5/ccle#Investigation\",\n \"label\": \"CCLE-BRCA\",\n \"uri\": \"https://www.sbgenomics.com/ccle/investigation/03\"\n },\n {\n \"type\": \"https://www.sbgenomics.com/ontologies/2016/5/ccle#Utility\",\n \"label\": \"CCLE-BRCA\",\n \"uri\": \"https://www.sbgenomics.com/ccle/investigation/03\"\n },\n {\n \"type\": \"http://www.w3.org/2000/01/rdf-schema#Resource\",\n \"label\": \"CCLE-BRCA\",\n \"uri\": \"https://www.sbgenomics.com/ccle/investigation/03\"\n }\n ]\n}",
"language": "json"
}
]
}
[/block]
For each result, the response lists:
* **Its `type`:** This is an URI assigned to a property within a [CGC-hosted database's namespace](http://docs.cancergenomicscloud.org/docs/sparql-basics#section-uniform-resource-identifiers) or within the [RDF Schema namespace defined by W3C](https://www.w3.org/TR/rdf-schema/#ch_summary) which contains the result.
* **Its `label`:** This is a human-readable form of a result.
* **Its `uri`:** This is an URI assigned to an entity and its ID within a [CGC-hosted database's namespace](http://docs.cancergenomicscloud.org/docs/sparql-basics#section-uniform-resource-identifiers).
Note if your search term does not match any results, empty brackets `[]` are returned.
\##Search by URI
Start from a free-text [search by term](#section-search-by-term) request, as described above. Use an `uri` obtained in the response as the starting point to obtain further details, including individual members matching the designated resource. Note that this `uri` must be in a [URL-encoded format](http://www.w3schools.com/tags/ref_urlencode.asp).
\###Path
[block:code]
{
"codes": [
{
"code": "http://cgc-datasets-api.sbgenomics.com/describe",
"language": "text",
"name": "Path"
}
]
}
[/block]
\###Header fields
[block:parameters]
{
"data": {
"0-0": "`X-SBG-Auth-Token`\nrequired",
"h-0": "Name",
"h-1": "Description",
"0-1": "Your CGC [authentication token](https://docs.cancergenomicscloud.org/docs/get-your-authentication-token)"
},
"cols": 2,
"rows": 1
}
[/block]
\###Query parameters
[block:parameters]
{
"data": {
"0-2": "Use an `uri` obtained via a [search by term](#section-search-by-term) request. Note that only exact results will be returned. This `uri` must be in a [URL-encoded format](http://www.w3schools.com/tags/ref_urlencode.asp).",
"0-0": "`uri`",
"h-0": "Name",
"h-1": "Datatype",
"h-2": "Description",
"0-1": "string"
},
"cols": 3,
"rows": 1
}
[/block]
\###Example request
[block:code]
{
"codes": [
{
"code": "GET /describe?uri=https%3A%2F%2Fwww.sbgenomics.com%2Fccle%2Finvestigation%2F03 HTTP/1.1\nHost: cgc-datasets-api.sbgenomics.com\nX-SBG-Auth-Token: 3210a98c1db9304ea9d9273156740f74",
"language": "http",
"name": "Example request"
}
]
}
[/block]
\###Example response
This will return a list of results from datasets accessible through the CGC, as shown below.
[block:code]
{
"codes": [
{
"code": "{\n \"tcga\": {},\n \"uri\": \"https://www.sbgenomics.com/ccle/investigation/03\",\n \"ccle\": {\n \"http://www.w3.org/2000/01/rdf-schema#label\": [\n \"CCLE-BRCA\"\n ],\n \"https://www.sbgenomics.com/ontologies/2016/5/ccle#hasInvestigation\": [\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-AU565\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-BT-20\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-BT-474\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-BT-483\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-BT-549\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-CAL-120\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-CAL-148\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-CAL-51\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-CAL-85-1\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-CAMA-1\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-DU4475\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-EFM-19\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-EFM-192A\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1143\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1143BL\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1187\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1395\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1419\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1428\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1500\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1569\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1599\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1806\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1937\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1954\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC1954BL\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC202\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC2157\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC2218\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC38\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HCC70\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HDQ-P1\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-HMC-1-8\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-Hs274.T\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-Hs281.T\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-Hs343.T\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-Hs578T\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-Hs606.T\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-Hs739.T\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-Hs742.T\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-JIMT-1\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-KPL-1\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-MCF7\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-MDA-MB-134-VI\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-MDA-MB-157\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-MDA-MB-175-VII\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-MDA-MB-231\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-MDA-MB-361\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-MDA-MB-415\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-MDA-MB-435S\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-MDA-MB-436\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-MDA-MB-453\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-MDA-MB-468\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-SK-BR-3\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-T-47D\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-UACC-812\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-UACC-893\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-ZR-75-1\",\n \"https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-ZR-75-30\"\n ],\n \"http://www.w3.org/1999/02/22-rdf-syntax-ns#type\": [\n \"http://www.w3.org/2002/07/owl#NamedIndividual\",\n \"https://www.sbgenomics.com/ontologies/2016/5/ccle#Investigation\",\n \"https://www.sbgenomics.com/ontologies/2016/5/ccle#Utility\",\n \"http://www.w3.org/2000/01/rdf-schema#Resource\"\n ]\n }\n}",
"language": "json"
}
]
}
[/block]
For each result, the response lists the URIs for the individual members of each property which matches your search terms. For instance, the cell line `https://www.sbgenomics.com/ccle/ccle_cell_line/CCLE-AU565` is returned for `https://www.sbgenomics.com/ontologies/2016/5/ccle#hasInvestigation`.
Note if your search term does not match any results, empty brackets `{}` are returned.