{"openapi":"3.1.0","info":{"title":"NBDC Human Database API","version":"1.0.0","description":"The public data of the NBDC Human Database portal, as JSON.\n\n**Two kinds of object.** A *research* is a study, published in numbered versions; a *dataset* is\none body of data belonging to exactly one research. A research is returned with the ids of its\ndatasets rather than with the datasets themselves, because each of them has an address of its own.\n\n**Nothing is authenticated.** Only published objects are ever returned, so there is nothing to\nauthenticate against. An unpublished object and one that never existed answer alike, and no\nendpoint tells them apart.\n\n**Where to start.** `GET /api/fields` lists what a search may be written against.\n`GET /api/research` and `GET /api/dataset` take that query and answer twenty at a time.\n`.jsonl` beside either name streams the whole published set instead, one object to a line.\n\n**Reading an answer.** Both languages are always included and neither falls back on the other:\n`ja` and `en` are what somebody wrote, not what the portal guessed. **A key that is\nabsent is a value nobody filled in; `null` means the value is known not to exist**, and that holds\nfor a list too: a list with nothing in it is an empty array, and a list known not to apply is\n`null`. `files` is the one exception, left out unless `includeFiles=true` is asked for, because\na research can hold over ten thousand of them. Prose is plain text — a link written inside a sentence\nkeeps its words and loses its destination, while the references a machine needs (accessions,\ndataset ids, vocabulary, files) are typed fields of their own.\n\n**What is promised.** The addresses, and nothing about what they respond with. A version can be\ncorrected in place without its number changing, so the same URL does not always give the same\nbytes, and there is no way offered of telling that it changed.","license":{"name":"Apache-2.0","identifier":"Apache-2.0"}},"servers":[{"url":"https://humandbs.dbcls.jp"}],"security":[],"tags":[{"name":"research","description":"Research entries and their versions."},{"name":"dataset","description":"Dataset entries."},{"name":"search","description":"What a search may be written against."},{"name":"dblink","description":"The correspondence between hum labels and JGA accessions."},{"name":"jga-date","description":"The dates of JGA accessions, supplied to DDBJ Search."}],"components":{"schemas":{"ResearchSearchResult":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageCount":{"type":"integer"},"query":{"type":"string","description":"The query as the portal read it back out. A query that means the same thing written two ways comes back the one way, which is what makes two searches comparable."},"hits":{"type":"array","items":{"$ref":"#/components/schemas/Research"},"description":"Twenty to a page. Each is the whole object, not a summary of it."}},"required":["total","page","pageCount","query","hits"],"description":"One page of a search. `total` counts the whole match, `pageCount` the pages it comes in — 0 when nothing matches; the whole published set is the bulk stream instead."},"Research":{"type":"object","properties":{"id":{"type":"string","description":"The hum label."},"version":{"type":"integer"},"url":{"type":"string","description":"The public page of this version, which is HTML. This API's own address for it is `/api/research/{id}/v{version}`."},"datePublished":{"type":"string","description":"When this version was released."},"versions":{"type":"array","items":{"type":"object","properties":{"version":{"type":"integer"},"datePublished":{"type":"string","description":"A calendar day, `YYYY-MM-DD`, cut in JST."}},"required":["version","datePublished"]},"description":"Every published version. The newest is when the research last changed."},"title":{"$ref":"#/components/schemas/Text"},"summary":{"type":"object","properties":{"aims":{"$ref":"#/components/schemas/Text"},"methods":{"$ref":"#/components/schemas/Text"},"targets":{"$ref":"#/components/schemas/Text"},"url":{"$ref":"#/components/schemas/Links"}}},"listingSummary":{"type":"object","properties":{"methods":{"$ref":"#/components/schemas/Text"},"targets":{"$ref":"#/components/schemas/Text"},"typeOfData":{"$ref":"#/components/schemas/Text"}}},"releaseNote":{"$ref":"#/components/schemas/Text"},"dataProviders":{"type":"array","items":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/Text"},"organization":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/Text"}}}},"required":["organization"]}},"researchProjects":{"type":"array","items":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/Text"},"url":{"$ref":"#/components/schemas/Links"}}}},"grants":{"type":"array","items":{"type":"object","properties":{"title":{"$ref":"#/components/schemas/Text"},"agency":{"$ref":"#/components/schemas/Text"},"grantIds":{"type":["array","null"],"items":{"type":"string"}}}}},"relatedPublications":{"type":"array","items":{"type":"object","properties":{"title":{"type":["string","null"]},"doi":{"type":["string","null"],"description":"As the research wrote it, which is usually a `https://doi.org/` URL."},"datasets":{"type":["array","null"],"items":{"type":"string"},"description":"Dataset ids the publication names: this research's that are published, then any other written by hand — another research's, or an accession the portal does not hold — as written. Null where the research states that the publication names no dataset."}}}},"datasets":{"type":"array","items":{"type":"string"},"description":"Dataset ids this version lists. Only published ones appear."},"controlledAccessUsers":{"type":"array","items":{"type":"object","properties":{"principalInvestigator":{"$ref":"#/components/schemas/Text"},"affiliation":{"$ref":"#/components/schemas/Text"},"country":{"$ref":"#/components/schemas/Text"},"researchTitle":{"$ref":"#/components/schemas/Text"},"periodStart":{"type":["string","null"],"description":"A calendar day, `YYYY-MM-DD`, cut in JST."},"periodEnd":{"type":["string","null"],"description":"A calendar day, `YYYY-MM-DD`, cut in JST."},"datasets":{"type":"array","items":{"type":"string"}}},"required":["principalInvestigator","affiliation","country","researchTitle","periodStart","periodEnd","datasets"]}},"files":{"type":"array","items":{"$ref":"#/components/schemas/File"},"description":"The files the research's public page lists: those under its prefix in the public bucket that are set to be listed on the research's page. A dataset's files are under the dataset. Present only when `includeFiles=true` was asked for: a research can hold over ten thousand files. The list is the prefix as it is now, whichever version was asked for."}},"required":["id","version","url","datePublished","versions","summary","listingSummary","dataProviders","researchProjects","grants","relatedPublications","datasets","controlledAccessUsers"],"description":"A study, at one of its published versions. **It has no date of its own** — `versions` holds every published one, and the last of them is when the research last changed. Its datasets appear as ids: each has an address of its own, and one research can hold hundreds."},"Text":{"type":"object","properties":{"ja":{"type":["string","null"]},"en":{"type":["string","null"]}},"description":"A value in both languages. A language with nothing to say is absent; `null` is a language whose value is known not to exist. Neither falls back on the other."},"Links":{"type":"object","properties":{"ja":{"type":["array","null"],"items":{"$ref":"#/components/schemas/Link"}},"en":{"type":["array","null"],"items":{"$ref":"#/components/schemas/Link"}}},"description":"Links whose two languages point at different resources. Unlike prose, these keep their destination: a reference a machine can use is a field of its own rather than something written inside a sentence."},"Link":{"type":"object","properties":{"url":{"type":"string"},"text":{"type":"string"}},"required":["url","text"],"description":"A destination and the words that stand for it."},"File":{"type":"object","properties":{"name":{"type":"string"},"size":{"type":"integer"},"url":{"type":"string"},"label":{"$ref":"#/components/schemas/Text"}},"required":["name","size","url"],"description":"A file as the store lists it. **The address is not promised**: its form is kept, but a file has a published state of its own that an administrator can turn off. `label` describes what the file holds where its name does not; it is absent when the file has none, and a language an administrator did not write is absent from it. It can change at any time, without a new version of the research."},"Problem":{"type":"object","properties":{"type":{"type":"string","description":"`https://humandbs.dbcls.jp/problems/` and one of `not-found`, `invalid-query`, `invalid-parameter`, `invalid-sort`, `invalid-order`, `unknown-accession-type`, `service-unavailable`. It names the kind of failure and is not a page to open."},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"code":{"type":"string","description":"On `invalid-query` only: the rule the query broke — `unexpected-token`, `unknown-field`, `invalid-operator-for-field`, `invalid-date-format`, `invalid-number-format`, `missing-value` or `too-complex`."},"column":{"type":"integer","description":"On `invalid-query` only: the 1-based position in `q` the failure is at."},"token":{"type":"string","description":"On `invalid-query`, where there is one: the part of `q` the failure is about."}},"required":["type","title","status","detail","instance"],"description":"RFC 7807 problem details. **A 404 reveals nothing about what was requested**: the sentence is fixed per kind of object and never repeats the label, because an unpublished object and one that never existed are not told apart."},"DatasetSearchResult":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"pageCount":{"type":"integer"},"query":{"type":"string","description":"The query as the portal read it back out. A query that means the same thing written two ways comes back the one way, which is what makes two searches comparable."},"hits":{"type":"array","items":{"$ref":"#/components/schemas/Dataset"},"description":"Twenty to a page. Each is the whole object, not a summary of it."}},"required":["total","page","pageCount","query","hits"],"description":"One page of a search. `total` counts the whole match, `pageCount` the pages it comes in — 0 when nothing matches; the whole published set is the bulk stream instead."},"Dataset":{"type":"object","properties":{"id":{"type":"string","description":"The dataset id."},"research":{"type":"string","description":"The hum label of the research it belongs to."},"url":{"type":"string","description":"The public page of the dataset, which is HTML. This API's own address for it is `/api/dataset/{id}`."},"datePublished":{"type":["string","null"],"description":"A calendar day, `YYYY-MM-DD`, cut in JST."},"dateModified":{"type":["string","null"],"description":"A calendar day, `YYYY-MM-DD`, cut in JST."},"values":{"type":"array","items":{"$ref":"#/components/schemas/Value"}},"experiments":{"type":"array","items":{"$ref":"#/components/schemas/Experiment"}},"dataVolume":{"type":"integer","description":"The total size of the dataset's files in bytes, as a reader downloads them: an archive's files as the archive distributes them, or the files the portal serves for a dataset whose id it issued (`NHA…`). Absent when it cannot be told, and for a dataset whose id the portal issued, absent unless `includeFiles=true` was asked for."},"fileFormats":{"type":"array","items":{"$ref":"#/components/schemas/Term"},"description":"The formats of the dataset's files, read off their names, as the `file-type` field's values."},"files":{"type":"array","items":{"$ref":"#/components/schemas/File"},"description":"The files this dataset selects, limited to those the research's public prefix lists. Present only when `includeFiles=true` was asked for."}},"required":["id","research","url","datePublished","dateModified","values","experiments","fileFormats"],"description":"One body of data, belonging to exactly one research. Its dates come from the archive that holds it where the portal has none of its own."},"Value":{"oneOf":[{"type":"object","properties":{"key":{"type":"string"},"label":{"$ref":"#/components/schemas/Text"},"type":{"type":"string","enum":["text"]},"text":{"$ref":"#/components/schemas/Text"}},"required":["key","label","type","text"]},{"type":"object","properties":{"key":{"type":"string"},"label":{"$ref":"#/components/schemas/Text"},"type":{"type":"string","enum":["single"]},"value":{"type":["string","null"]}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":"string"},"label":{"$ref":"#/components/schemas/Text"},"type":{"type":"string","enum":["accession"]},"value":{"type":["string","null"]}},"required":["key","label","type","value"]},{"type":"object","properties":{"key":{"type":"string"},"label":{"$ref":"#/components/schemas/Text"},"type":{"type":"string","enum":["vocabulary"]},"terms":{"type":["array","null"],"items":{"$ref":"#/components/schemas/Term"}}},"required":["key","label","type","terms"]},{"type":"object","properties":{"key":{"type":"string"},"label":{"$ref":"#/components/schemas/Text"},"type":{"type":"string","enum":["number"]},"numbers":{"type":["array","null"],"items":{"$ref":"#/components/schemas/NumberValue"}}},"required":["key","label","type","numbers"]},{"type":"object","properties":{"key":{"type":"string"},"label":{"$ref":"#/components/schemas/Text"},"type":{"type":"string","enum":["disease"]},"diseases":{"type":["array","null"],"items":{"$ref":"#/components/schemas/Disease"}}},"required":["key","label","type","diseases"]}],"description":"A value under a catalog key. `type` indicates which of the payloads is present, and `key` is the code `/api/fields` lists it under."},"Term":{"type":"object","properties":{"code":{"type":"string"},"label":{"$ref":"#/components/schemas/Text"}},"required":["code","label"],"description":"A vocabulary value. `code` is the spelling a query names it by, so a value found here can be written straight into `?q=`."},"NumberValue":{"type":"object","properties":{"value":{"type":"number"},"unit":{"type":["string","null"]},"high":{"type":["number","null"]},"prefix":{"$ref":"#/components/schemas/Text"},"suffix":{"$ref":"#/components/schemas/Text"}},"required":["value","unit","high"],"description":"A number in the key's canonical unit, which is the unit `/api/fields` gives for that field and not necessarily the one it was entered in; `null` for a field that counts. `prefix` and `suffix` are what the page writes before and after the number, spaces included (`\"常染色体: \"`, `\" SNVs\"`). Both are absent when there is none, and a value in one language only where a curator gave just that one. `high` is the upper end of a value written as a width, and `null` on every number that is not one."},"Disease":{"type":"object","properties":{"terms":{"type":"array","items":{"$ref":"#/components/schemas/Term"}},"name":{"$ref":"#/components/schemas/Text"}},"required":["terms","name"],"description":"What classifications call it, and what the research called it. **`terms` may be empty** — a disease no classification names is an ordinary value, so a code cannot be assumed to be there."},"Experiment":{"type":"object","properties":{"label":{"$ref":"#/components/schemas/Text"},"values":{"type":"array","items":{"$ref":"#/components/schemas/Value"}}},"required":["values"],"description":"One run within a dataset. It has no address and no identifier of its own: it is part of how the dataset describes itself."},"SearchFields":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/SearchField"}}},"required":["fields"],"description":"Everything `?q=` can be written against, in the order the portal shows them."},"SearchField":{"type":"object","properties":{"code":{"type":"string","description":"How a query names the field."},"type":{"type":"string","enum":["identifier","text","date","term","number"]},"label":{"type":"object","properties":{"ja":{"type":["string","null"]},"en":{"type":["string","null"]}},"description":"The name the portal shows for the field: the catalog's, or the search screen's for the built-in fields (`id`, `title`, `date_published`, `date_modified`, `file-type`)."},"unit":{"type":"string","description":"The unit the stored values are in."},"values":{"type":"array","items":{"$ref":"#/components/schemas/Term"},"description":"Every value the published set has, at the level a query can name it."}},"required":["code","type"],"description":"A field a query may name. **`type` is what the query language makes of it**, which decides the forms a value may take: `identifier` a prefix pattern, `text` a value contained anywhere, `date` and `number` a range, `term` one of `values` — codes out of a closed set. The `?q=` parameter of the search endpoints says what each means."},"DbLinkTypes":{"type":"object","properties":{"types":{"type":"array","items":{"$ref":"#/components/schemas/AccessionType"}}},"required":["types"],"description":"The accession types `/api/dblink/{type}` accepts."},"AccessionType":{"type":"string","enum":["humandbs","jga-dataset","jga-study"],"description":"Which side of the correspondence an identifier is from: `humandbs` a hum label, `jga-dataset` a JGAD accession, `jga-study` a JGAS accession."},"DbLinks":{"type":"object","properties":{"identifier":{"type":"string"},"type":{"$ref":"#/components/schemas/AccessionType"},"dbXrefs":{"type":"array","items":{"$ref":"#/components/schemas/Xref"},"description":"Related entries, by type then identifier. Empty when there are none."}},"required":["identifier","type","dbXrefs"],"description":"What one accession is linked to. **Only researches the portal has published take part**, so an accession whose research is unpublished returns the same as one nobody has heard of: 200 with an empty list."},"Xref":{"type":"object","properties":{"identifier":{"type":"string"},"type":{"$ref":"#/components/schemas/AccessionType"},"url":{"type":"string","description":"Where the entry can be read, as HTML: a research's public page (`/hum0001`, which redirects to its latest version), or a JGA entry's page on DDBJ Search."}},"required":["identifier","type","url"],"description":"An entry on the other side of a correspondence, and where it can be read."},"JgaDateTypes":{"type":"object","properties":{"types":{"type":"array","items":{"$ref":"#/components/schemas/JgaDateType"}}},"required":["types"],"description":"The accession types `/api/jga-date/{type}` accepts."},"JgaDateType":{"type":"string","enum":["jga-study","jga-dataset","jga-dac","jga-policy"],"description":"The index DDBJ Search files a JGA accession under: `jga-study` a JGAS, `jga-dataset` a JGAD, `jga-dac` a JGAC, `jga-policy` a JGAP."},"JgaDate":{"type":"object","properties":{"identifier":{"type":"string","description":"The accession."},"type":{"$ref":"#/components/schemas/JgaDateType"},"dateCreated":{"type":["string","null"],"description":"The day the accession was issued."},"datePublished":{"type":["string","null"],"description":"The day the accession was first released."},"dateModified":{"type":["string","null"],"description":"The day the registered XML was last changed. Never before `datePublished`."}},"required":["identifier","type","dateCreated","datePublished","dateModified"],"description":"When one public JGA accession was created, published and last changed. Each is a calendar day in Japan (`YYYY-MM-DD`). Every accession the application system has released is listed, whether or not the portal has published a research for it."}},"parameters":{}},"paths":{"/api/research":{"get":{"operationId":"searchResearch","tags":["research"],"summary":"Search published researches","description":"Each hit is the whole research at its latest published version. A research matches when its own text or any of its published datasets does.","parameters":[{"schema":{"type":"string","description":"The query language, which is the one the site's own addresses use — a query written here works\nin the browser and back.\n\nA Lucene subset, spelled the way ddbj-search-api's db-portal spells it.\n\n| written | means |\n| --- | --- |\n| `word` | free text: rows whose indexed text contains it anywhere, inside a longer word too (`diabet` finds diabetes). Case does not matter |\n| `word*` | the same as `word`: free text already matches inside words, so a trailing `*` is dropped. `*` or `?` anywhere else is refused |\n| `two words` | both, each anywhere (`AND`) |\n| `\"two words\"` | the characters in that order, the space included. Quoting is also how a value holding a bracket, a colon or an operator word is written |\n| `-word` `+word` | the sign is part of the word: `-cancer` finds \"-cancer\", so gene names such as `HIF-1` can be written as they are. Exclude with `NOT` |\n| `field:value` | constrains to one field of `GET /api/fields`. Field names are case-sensitive; what a value means depends on the field's `type` (below) |\n| `field:[a TO b]` | a range, both ends included, on a `date` or a `number` field. `*` is an end that is not there |\n| `id:value*` `id:value?` | a prefix pattern, on `id` only: `*` any run, `?` one character. At least two characters before the first of them, all of `A-Z a-z 0-9 _ . -` |\n| `AND` `OR` `NOT` | uppercase only; lowercase `and` `or` `not` are words. Two terms side by side mean `AND`, and `AND` binds tighter than `OR` |\n| `( )` | grouping |\n\nBoost, fuzzy and regular expressions are not part of it.\n\n**A value by the field's `type`.** `identifier` (`id`): the whole label, case ignored — a hum label on\nthe research listing, a dataset id on the dataset listing. `text` (`title`): contained anywhere, like\nfree text, and a trailing `*` is dropped. `date`: a day, `YYYY-MM-DD`. `number`: a plain decimal,\nin the field's `unit`. `term`: one of the field's `values[].code`, case ignored; a code the list does\nnot hold matches nothing (200, `total` 0) rather than being refused. A `disease` code is ICD-10, with or\nwithout its point (`E14.2` is `E142`), and a three-character code also matches the codes under it.\n\n**Dates on the research listing are the research's**: `date_published` is when its first version was\npublished and `date_modified` when its latest was, while `datePublished` in an answer is the date of\nthe version returned. On the dataset listing both are the dataset's own. Fields in `q` are snake_case;\nthe `sort` keys are camelCase and order by the same dates.\n\n**JGA accessions** may be written with eleven digits, as JGA and DDBJ Search also write them:\n`JGAS00000000197` is read as `JGAS000197`. A JGA study (`JGAS`) finds the datasets under it.\n\nA query that cannot be read answers 422 with `code`, `column` (1-based) and `token`, and the\n`query` of a 200 answer is the query as it was read, written back.\n\n**`GET /api/fields` lists the fields**, and the values every `term` field takes. **Prose is not\naddressable**: a row's indexed text holds the words of every free-text key but not which key they\ncame from, so they are reachable as `word` and not as `key:word`. **`id` is a research's hum\nlabel on one listing and a dataset's own accession on the other**, so one query means two things\nacross the two.\n\nExamples:\n\n- `cancer`\n- `\"lung cancer\"`\n- `diabet*`\n- `title:\"genome\" AND date_published:[2020-01-01 TO *]`\n- `cancer NOT disease:C22`\n- `(disease:C22 OR disease:C34) AND read-length:[100 TO *]`\n- `id:hum00*`"},"required":false,"description":"The query language, which is the one the site's own addresses use — a query written here works\nin the browser and back.\n\nA Lucene subset, spelled the way ddbj-search-api's db-portal spells it.\n\n| written | means |\n| --- | --- |\n| `word` | free text: rows whose indexed text contains it anywhere, inside a longer word too (`diabet` finds diabetes). Case does not matter |\n| `word*` | the same as `word`: free text already matches inside words, so a trailing `*` is dropped. `*` or `?` anywhere else is refused |\n| `two words` | both, each anywhere (`AND`) |\n| `\"two words\"` | the characters in that order, the space included. Quoting is also how a value holding a bracket, a colon or an operator word is written |\n| `-word` `+word` | the sign is part of the word: `-cancer` finds \"-cancer\", so gene names such as `HIF-1` can be written as they are. Exclude with `NOT` |\n| `field:value` | constrains to one field of `GET /api/fields`. Field names are case-sensitive; what a value means depends on the field's `type` (below) |\n| `field:[a TO b]` | a range, both ends included, on a `date` or a `number` field. `*` is an end that is not there |\n| `id:value*` `id:value?` | a prefix pattern, on `id` only: `*` any run, `?` one character. At least two characters before the first of them, all of `A-Z a-z 0-9 _ . -` |\n| `AND` `OR` `NOT` | uppercase only; lowercase `and` `or` `not` are words. Two terms side by side mean `AND`, and `AND` binds tighter than `OR` |\n| `( )` | grouping |\n\nBoost, fuzzy and regular expressions are not part of it.\n\n**A value by the field's `type`.** `identifier` (`id`): the whole label, case ignored — a hum label on\nthe research listing, a dataset id on the dataset listing. `text` (`title`): contained anywhere, like\nfree text, and a trailing `*` is dropped. `date`: a day, `YYYY-MM-DD`. `number`: a plain decimal,\nin the field's `unit`. `term`: one of the field's `values[].code`, case ignored; a code the list does\nnot hold matches nothing (200, `total` 0) rather than being refused. A `disease` code is ICD-10, with or\nwithout its point (`E14.2` is `E142`), and a three-character code also matches the codes under it.\n\n**Dates on the research listing are the research's**: `date_published` is when its first version was\npublished and `date_modified` when its latest was, while `datePublished` in an answer is the date of\nthe version returned. On the dataset listing both are the dataset's own. Fields in `q` are snake_case;\nthe `sort` keys are camelCase and order by the same dates.\n\n**JGA accessions** may be written with eleven digits, as JGA and DDBJ Search also write them:\n`JGAS00000000197` is read as `JGAS000197`. A JGA study (`JGAS`) finds the datasets under it.\n\nA query that cannot be read answers 422 with `code`, `column` (1-based) and `token`, and the\n`query` of a 200 answer is the query as it was read, written back.\n\n**`GET /api/fields` lists the fields**, and the values every `term` field takes. **Prose is not\naddressable**: a row's indexed text holds the words of every free-text key but not which key they\ncame from, so they are reachable as `word` and not as `key:word`. **`id` is a research's hum\nlabel on one listing and a dataset's own accession on the other**, so one query means two things\nacross the two.\n\nExamples:\n\n- `cancer`\n- `\"lung cancer\"`\n- `diabet*`\n- `title:\"genome\" AND date_published:[2020-01-01 TO *]`\n- `cancer NOT disease:C22`\n- `(disease:C22 OR disease:C34) AND read-length:[100 TO *]`\n- `id:hum00*`","name":"q","in":"query"},{"schema":{"type":"string","enum":["dateModified","datePublished","id"],"description":"Which key the results are ordered by. Defaults to `dateModified`."},"required":false,"description":"Which key the results are ordered by. Defaults to `dateModified`.","name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Which way that key runs. Defaults to `desc` for a date and `asc` for `id`, so a listing opens on what changed last and identifiers read in the order they were issued."},"required":false,"description":"Which way that key runs. Defaults to `desc` for a date and `asc` for `id`, so a listing opens on what changed last and identifiers read in the order they were issued.","name":"order","in":"query"},{"schema":{"type":"integer","minimum":1,"description":"1-based. Twenty rows to a page, always: there is no page-size parameter, and `limit` or `size` are ignored. The whole corpus is the bulk stream. A page past the last answers an empty `hits`."},"required":false,"description":"1-based. Twenty rows to a page, always: there is no page-size parameter, and `limit` or `size` are ignored. The whole corpus is the bulk stream. A page past the last answers an empty `hits`.","name":"page","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422."},"required":false,"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422.","name":"includeFiles","in":"query"}],"responses":{"200":{"description":"Matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchSearchResult"}}}},"422":{"description":"A parameter could not be read: the query (`invalid-query`, with `code`, `column` and `token`), an ordering that is not available (`invalid-sort`, `invalid-order`), or the page or `includeFiles` (`invalid-parameter`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"The search cannot run now (`service-unavailable`): too many are running. Send the same request again after the number of seconds in the `Retry-After` header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/research.jsonl":{"get":{"operationId":"bulkResearch","tags":["research"],"summary":"Every published research","description":"One research per line, at its latest published version, by hum label. It takes no query: to stream part of the set, page through the search instead.","parameters":[{"schema":{"type":"string","enum":["true","false"],"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422."},"required":false,"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422.","name":"includeFiles","in":"query"}],"responses":{"200":{"description":"One research per line.","content":{"application/x-ndjson":{"schema":{"$ref":"#/components/schemas/Research"}}}},"422":{"description":"`includeFiles` is neither `true` nor `false`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"The search cannot run now (`service-unavailable`): too many are running. Send the same request again after the number of seconds in the `Retry-After` header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/research/{humId}":{"get":{"operationId":"getResearch","tags":["research"],"summary":"The latest published version of a research","description":"A hum label that has been superseded resolves too, and is answered rather than redirected — the `id` and `url` of the answer name the label that is current now, so a caller following a citation learns which one that is from the body.","parameters":[{"schema":{"type":"string","description":"A hum label, `hum` and four digits. Case is ignored, and a superseded one resolves too.","example":"hum0001"},"required":true,"description":"A hum label, `hum` and four digits. Case is ignored, and a superseded one resolves too.","name":"humId","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422."},"required":false,"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422.","name":"includeFiles","in":"query"}],"responses":{"200":{"description":"The research.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Research"}}}},"404":{"description":"No published object has that label.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"`includeFiles` is neither `true` nor `false`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/research/{humId}/{version}":{"get":{"operationId":"getResearchVersion","tags":["research"],"summary":"One published version of a research","description":"A version that was never published, or has been withdrawn, returns 404 like a number that was never issued. Every version that can be asked for is listed on the research.","parameters":[{"schema":{"type":"string","description":"A hum label, `hum` and four digits. Case is ignored, and a superseded one resolves too.","example":"hum0001"},"required":true,"description":"A hum label, `hum` and four digits. Case is ignored, and a superseded one resolves too.","name":"humId","in":"path"},{"schema":{"type":"string","pattern":"^v[1-9][0-9]*$","description":"The version, written `v3` as in the page's URL. `3`, `v03` and `V3` are not versions and answer 404.","example":"v1"},"required":true,"description":"The version, written `v3` as in the page's URL. `3`, `v03` and `V3` are not versions and answer 404.","name":"version","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422."},"required":false,"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422.","name":"includeFiles","in":"query"}],"responses":{"200":{"description":"The version.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Research"}}}},"404":{"description":"No published object has that label.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"`includeFiles` is neither `true` nor `false`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/dataset":{"get":{"operationId":"searchDatasets","tags":["dataset"],"summary":"Search published datasets","description":"Each hit is the whole dataset. The query is the one the research listing takes — the search rows of a research include the values of its datasets, so a query can be moved between the two listings and keeps its meaning.","parameters":[{"schema":{"type":"string","description":"The query language, which is the one the site's own addresses use — a query written here works\nin the browser and back.\n\nA Lucene subset, spelled the way ddbj-search-api's db-portal spells it.\n\n| written | means |\n| --- | --- |\n| `word` | free text: rows whose indexed text contains it anywhere, inside a longer word too (`diabet` finds diabetes). Case does not matter |\n| `word*` | the same as `word`: free text already matches inside words, so a trailing `*` is dropped. `*` or `?` anywhere else is refused |\n| `two words` | both, each anywhere (`AND`) |\n| `\"two words\"` | the characters in that order, the space included. Quoting is also how a value holding a bracket, a colon or an operator word is written |\n| `-word` `+word` | the sign is part of the word: `-cancer` finds \"-cancer\", so gene names such as `HIF-1` can be written as they are. Exclude with `NOT` |\n| `field:value` | constrains to one field of `GET /api/fields`. Field names are case-sensitive; what a value means depends on the field's `type` (below) |\n| `field:[a TO b]` | a range, both ends included, on a `date` or a `number` field. `*` is an end that is not there |\n| `id:value*` `id:value?` | a prefix pattern, on `id` only: `*` any run, `?` one character. At least two characters before the first of them, all of `A-Z a-z 0-9 _ . -` |\n| `AND` `OR` `NOT` | uppercase only; lowercase `and` `or` `not` are words. Two terms side by side mean `AND`, and `AND` binds tighter than `OR` |\n| `( )` | grouping |\n\nBoost, fuzzy and regular expressions are not part of it.\n\n**A value by the field's `type`.** `identifier` (`id`): the whole label, case ignored — a hum label on\nthe research listing, a dataset id on the dataset listing. `text` (`title`): contained anywhere, like\nfree text, and a trailing `*` is dropped. `date`: a day, `YYYY-MM-DD`. `number`: a plain decimal,\nin the field's `unit`. `term`: one of the field's `values[].code`, case ignored; a code the list does\nnot hold matches nothing (200, `total` 0) rather than being refused. A `disease` code is ICD-10, with or\nwithout its point (`E14.2` is `E142`), and a three-character code also matches the codes under it.\n\n**Dates on the research listing are the research's**: `date_published` is when its first version was\npublished and `date_modified` when its latest was, while `datePublished` in an answer is the date of\nthe version returned. On the dataset listing both are the dataset's own. Fields in `q` are snake_case;\nthe `sort` keys are camelCase and order by the same dates.\n\n**JGA accessions** may be written with eleven digits, as JGA and DDBJ Search also write them:\n`JGAS00000000197` is read as `JGAS000197`. A JGA study (`JGAS`) finds the datasets under it.\n\nA query that cannot be read answers 422 with `code`, `column` (1-based) and `token`, and the\n`query` of a 200 answer is the query as it was read, written back.\n\n**`GET /api/fields` lists the fields**, and the values every `term` field takes. **Prose is not\naddressable**: a row's indexed text holds the words of every free-text key but not which key they\ncame from, so they are reachable as `word` and not as `key:word`. **`id` is a research's hum\nlabel on one listing and a dataset's own accession on the other**, so one query means two things\nacross the two.\n\nExamples:\n\n- `cancer`\n- `\"lung cancer\"`\n- `diabet*`\n- `title:\"genome\" AND date_published:[2020-01-01 TO *]`\n- `cancer NOT disease:C22`\n- `(disease:C22 OR disease:C34) AND read-length:[100 TO *]`\n- `id:hum00*`"},"required":false,"description":"The query language, which is the one the site's own addresses use — a query written here works\nin the browser and back.\n\nA Lucene subset, spelled the way ddbj-search-api's db-portal spells it.\n\n| written | means |\n| --- | --- |\n| `word` | free text: rows whose indexed text contains it anywhere, inside a longer word too (`diabet` finds diabetes). Case does not matter |\n| `word*` | the same as `word`: free text already matches inside words, so a trailing `*` is dropped. `*` or `?` anywhere else is refused |\n| `two words` | both, each anywhere (`AND`) |\n| `\"two words\"` | the characters in that order, the space included. Quoting is also how a value holding a bracket, a colon or an operator word is written |\n| `-word` `+word` | the sign is part of the word: `-cancer` finds \"-cancer\", so gene names such as `HIF-1` can be written as they are. Exclude with `NOT` |\n| `field:value` | constrains to one field of `GET /api/fields`. Field names are case-sensitive; what a value means depends on the field's `type` (below) |\n| `field:[a TO b]` | a range, both ends included, on a `date` or a `number` field. `*` is an end that is not there |\n| `id:value*` `id:value?` | a prefix pattern, on `id` only: `*` any run, `?` one character. At least two characters before the first of them, all of `A-Z a-z 0-9 _ . -` |\n| `AND` `OR` `NOT` | uppercase only; lowercase `and` `or` `not` are words. Two terms side by side mean `AND`, and `AND` binds tighter than `OR` |\n| `( )` | grouping |\n\nBoost, fuzzy and regular expressions are not part of it.\n\n**A value by the field's `type`.** `identifier` (`id`): the whole label, case ignored — a hum label on\nthe research listing, a dataset id on the dataset listing. `text` (`title`): contained anywhere, like\nfree text, and a trailing `*` is dropped. `date`: a day, `YYYY-MM-DD`. `number`: a plain decimal,\nin the field's `unit`. `term`: one of the field's `values[].code`, case ignored; a code the list does\nnot hold matches nothing (200, `total` 0) rather than being refused. A `disease` code is ICD-10, with or\nwithout its point (`E14.2` is `E142`), and a three-character code also matches the codes under it.\n\n**Dates on the research listing are the research's**: `date_published` is when its first version was\npublished and `date_modified` when its latest was, while `datePublished` in an answer is the date of\nthe version returned. On the dataset listing both are the dataset's own. Fields in `q` are snake_case;\nthe `sort` keys are camelCase and order by the same dates.\n\n**JGA accessions** may be written with eleven digits, as JGA and DDBJ Search also write them:\n`JGAS00000000197` is read as `JGAS000197`. A JGA study (`JGAS`) finds the datasets under it.\n\nA query that cannot be read answers 422 with `code`, `column` (1-based) and `token`, and the\n`query` of a 200 answer is the query as it was read, written back.\n\n**`GET /api/fields` lists the fields**, and the values every `term` field takes. **Prose is not\naddressable**: a row's indexed text holds the words of every free-text key but not which key they\ncame from, so they are reachable as `word` and not as `key:word`. **`id` is a research's hum\nlabel on one listing and a dataset's own accession on the other**, so one query means two things\nacross the two.\n\nExamples:\n\n- `cancer`\n- `\"lung cancer\"`\n- `diabet*`\n- `title:\"genome\" AND date_published:[2020-01-01 TO *]`\n- `cancer NOT disease:C22`\n- `(disease:C22 OR disease:C34) AND read-length:[100 TO *]`\n- `id:hum00*`","name":"q","in":"query"},{"schema":{"type":"string","enum":["dateModified","datePublished","id"],"description":"Which key the results are ordered by. Defaults to `dateModified`."},"required":false,"description":"Which key the results are ordered by. Defaults to `dateModified`.","name":"sort","in":"query"},{"schema":{"type":"string","enum":["asc","desc"],"description":"Which way that key runs. Defaults to `desc` for a date and `asc` for `id`, so a listing opens on what changed last and identifiers read in the order they were issued."},"required":false,"description":"Which way that key runs. Defaults to `desc` for a date and `asc` for `id`, so a listing opens on what changed last and identifiers read in the order they were issued.","name":"order","in":"query"},{"schema":{"type":"integer","minimum":1,"description":"1-based. Twenty rows to a page, always: there is no page-size parameter, and `limit` or `size` are ignored. The whole corpus is the bulk stream. A page past the last answers an empty `hits`."},"required":false,"description":"1-based. Twenty rows to a page, always: there is no page-size parameter, and `limit` or `size` are ignored. The whole corpus is the bulk stream. A page past the last answers an empty `hits`.","name":"page","in":"query"},{"schema":{"type":"string","enum":["true","false"],"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422."},"required":false,"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422.","name":"includeFiles","in":"query"}],"responses":{"200":{"description":"Matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DatasetSearchResult"}}}},"422":{"description":"A parameter could not be read: the query (`invalid-query`, with `code`, `column` and `token`), an ordering that is not available (`invalid-sort`, `invalid-order`), or the page or `includeFiles` (`invalid-parameter`).","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"The search cannot run now (`service-unavailable`): too many are running. Send the same request again after the number of seconds in the `Retry-After` header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/dataset.jsonl":{"get":{"operationId":"bulkDatasets","tags":["dataset"],"summary":"Every published dataset","description":"One dataset per line, by dataset id. It takes no query: to stream part of the set, page through the search instead.","parameters":[{"schema":{"type":"string","enum":["true","false"],"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422."},"required":false,"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422.","name":"includeFiles","in":"query"}],"responses":{"200":{"description":"One dataset per line.","content":{"application/x-ndjson":{"schema":{"$ref":"#/components/schemas/Dataset"}}}},"422":{"description":"`includeFiles` is neither `true` nor `false`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"503":{"description":"The search cannot run now (`service-unavailable`): too many are running. Send the same request again after the number of seconds in the `Retry-After` header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/dataset/{datasetId}":{"get":{"operationId":"getDataset","tags":["dataset"],"summary":"A published dataset","description":"A dataset id the portal issued and an accession it took from an archive are both answered here. A superseded id resolves and is answered rather than redirected.","parameters":[{"schema":{"type":"string","description":"A dataset id: a JGA dataset (`JGAD000001`), an archive's accession (`DRA000908`, `E-GEAD-1107`, `MTBKS1`) or one the portal issued (`NHA000001`). Case is ignored, and a superseded one resolves too.","example":"JGAD000001"},"required":true,"description":"A dataset id: a JGA dataset (`JGAD000001`), an archive's accession (`DRA000908`, `E-GEAD-1107`, `MTBKS1`) or one the portal issued (`NHA000001`). Case is ignored, and a superseded one resolves too.","name":"datasetId","in":"path"},{"schema":{"type":"string","enum":["true","false"],"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422."},"required":false,"description":"Whether to return `files`. Defaults to `false`, which leaves the key out rather than answering an empty list: a research can hold over ten thousand files, one of them more than 2 MB of answer. Anything but `true` or `false` is refused with 422.","name":"includeFiles","in":"query"}],"responses":{"200":{"description":"The dataset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Dataset"}}}},"404":{"description":"No published object has that label.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"422":{"description":"`includeFiles` is neither `true` nor `false`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/fields":{"get":{"operationId":"listSearchFields","tags":["search"],"summary":"The fields a query may name, and the values they take","description":"Everything `?q=` can be written against, and nothing else is: a name not listed here answers 422 `unknown-field`. A `term` field lists the values the published set has, so a value taken from here always matches something; a `number` field gives the unit its values are stored in. The first ones (`id`, `title`, `date_published`, `date_modified`, `file-type`) are the search row's own; `file-type` is the formats read off a dataset's files. **Not every key in an answer is a field**: a number the portal does not filter by (`coverage-depth` and the like) and every free-text key are reached through free text only.","responses":{"200":{"description":"The fields.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchFields"}}}},"503":{"description":"The search cannot run now (`service-unavailable`): too many are running. Send the same request again after the number of seconds in the `Retry-After` header.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/dblink":{"get":{"operationId":"listDbLinkTypes","tags":["dblink"],"summary":"The accession types the correspondence covers","description":"What may be written as `{type}` below. Anything else is refused rather than answered empty, so a typo does not look like an accession nobody has heard of.","responses":{"200":{"description":"The types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DbLinkTypes"}}}}}}},"/api/dblink/{type}":{"get":{"operationId":"listDbLinks","tags":["dblink"],"summary":"The whole correspondence, from one side","description":"One subject per line. Only researches the portal has published take part, so an accession whose research is not published is simply absent.","parameters":[{"schema":{"$ref":"#/components/schemas/AccessionType"},"required":true,"description":"Which side of the correspondence an identifier is from: `humandbs` a hum label, `jga-dataset` a JGAD accession, `jga-study` a JGAS accession.","name":"type","in":"path"}],"responses":{"200":{"description":"One subject per line.","content":{"application/x-ndjson":{"schema":{"$ref":"#/components/schemas/DbLinks"}}}},"422":{"description":"The type is not one of `GET /api/dblink`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/dblink/{type}/{id}":{"get":{"operationId":"getDbLinks","tags":["dblink"],"summary":"What one accession is linked to","description":"An accession nobody has heard of and one whose research is not published answer the same: 200 with an empty list.","parameters":[{"schema":{"$ref":"#/components/schemas/AccessionType"},"required":true,"description":"Which side of the correspondence an identifier is from: `humandbs` a hum label, `jga-dataset` a JGAD accession, `jga-study` a JGAS accession.","name":"type","in":"path"},{"schema":{"type":"string","description":"The accession, as that side writes it: `JGAS000001` for `jga-study`, `JGAD000001` for `jga-dataset`, `hum0001` for `humandbs`. Matched as written, case included — `jgas000001` answers the empty list.","example":"JGAS000001"},"required":true,"description":"The accession, as that side writes it: `JGAS000001` for `jga-study`, `JGAD000001` for `jga-dataset`, `hum0001` for `humandbs`. Matched as written, case included — `jgas000001` answers the empty list.","name":"id","in":"path"}],"responses":{"200":{"description":"The links.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DbLinks"}}}},"422":{"description":"The type is not one of `GET /api/dblink`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}},"/api/jga-date":{"get":{"operationId":"listJgaDateTypes","tags":["jga-date"],"summary":"The accession types the dates cover","description":"What may be written as `{type}` below: the four JGA indexes of DDBJ Search. Anything else is refused rather than answered empty.","responses":{"200":{"description":"The types.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JgaDateTypes"}}}}}}},"/api/jga-date/{type}":{"get":{"operationId":"listJgaDates","tags":["jga-date"],"summary":"The dates of every public JGA accession of one type","description":"One accession per line, by accession. Every accession the application system has released is listed, whether or not the portal has published a research for it: this is what DDBJ Search reads the dates of its JGA entries from. `dateCreated` is the day the accession was issued, `datePublished` the day of its first release, and `dateModified` the day its registered XML last changed, never before `datePublished`. Each is a calendar day in Japan.","parameters":[{"schema":{"$ref":"#/components/schemas/JgaDateType"},"required":true,"description":"The index DDBJ Search files a JGA accession under: `jga-study` a JGAS, `jga-dataset` a JGAD, `jga-dac` a JGAC, `jga-policy` a JGAP.","name":"type","in":"path"}],"responses":{"200":{"description":"One accession per line.","content":{"application/x-ndjson":{"schema":{"$ref":"#/components/schemas/JgaDate"}}}},"422":{"description":"The type is not one of `GET /api/jga-date`.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}},"webhooks":{}}