Welcome to the Neighbors REST API
The Neighbors REST API gives access to genome sequences via the taxonomy
of sequenced life.
Starting from one or more target organisms, the accessions of their
genomes can be looked up. In addition, the genome accessions of the
targets' closest relatives, their neighbors, can be looked up. Such
pairs of samples of target and neighbor genomes make good starting
material for developing diagnostic markers.
We use the
taxonomy
and
genome lists
supplied by the
NCBI
to build a custom database, neidb. The files we used for the construction of the
database as well as the resulting sqlite database may be downloaded from
here.
This directory includes a history of previous databases.
The construction files are bundled in tgz archives, while the databases
are marked with a .db file extension.
Our REST API for querying neidb is implemented in
the Neighbors server,
never,
developed by us, the
Research Group Bioinformatics
at the
Max-Planck-Institute for Evolutionary Biology
using our
Neighbors
package.
For more details on genetic marker discovery from whole genome
sequences with Neighbors and related software, please read
our
publication.
On API versioning:
Never follows a major/minor release schema. Major releases might change any aspect of an endpoint, including
its removal. All major releases remain online, to ensure backward compatibility.
This means you can reach all major API versions with this prefix: "/api/v[release]". Each API prefix,
i.e.:"/api/v1", "/api/v2", provides access to the latest minor release within that major release.
Minor releases follow an add-only strategy, which means endpoints, schemas, and parameters may be added,
but all previous URIs and schemas are left unchanged. The only exceptions to this rule are security updates.
These take precedent and will lead to the required changes in all releases.
API Version: 2.0
Base URL: https://neighbors.evolbio.mpg.de/api/v2
OpenAPI version: 3.0.0
OpenAPI document:
/docs/api/v2/static/api_spec.json
Endpoints
Accession
GET
/accessions
Get accessions and their assembly levels filtered by accession IDs
Description
Get accessions and their assembly levels filtered by accession IDs
Path Parameters
None
Query Parameters
Name
accession_ids
Description
IDs of accessions to filter for
Type
string[]
Required
true
Example
GCF_000001405.40,GCA_000002115.2
Name
offset
Description
Offset of entries when retrieving lists
Type
integer
Required
false
Extra
Minimum: 0, Default: 0
Example
0
Name
limit
Description
Amount of entries per response
Type
integer
Required
false
Extra
Minimum: -1, Default: -1
Example
20
Name
plain_data
Description
Reduce response to the data property and remove all hyper refereces
Type
boolean
Required
false
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
[
{
"accession": "GCF_000001405.40",
"level": "chromosome"
},
{
"accession": "GCA_000002115.2",
"level": "chromosome"
}
]
Schema
{
"data": [
{
"links": [
{
"action": "string",
"href": "string",
"rel": "string",
"types": [
"string"
]
}
],
"accession": "string",
"level": "string"
}
],
"links": [
{
"rel": "string",
"types": [
"string"
],
"action": "string",
"href": "string"
}
]
}
Code
Description
200
OK
400
Bad Request
404
Not Found
406
Not Acceptable
500
Internal Server Error
503
Service Unavailable
GET
/accessions/{accession_id}
Get accession and its assembly level
Description
Get accession and its assembly level
Path Parameters
Name
accession_id
Description
Accession to look up
Type
string
Required
true
Example
GCF_000001405.40
Query Parameters
Name
plain_data
Description
Reduce response to the data property and remove all hyper refereces
Type
boolean
Required
false
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
{
"accession": "GCF_000001405.40",
"level": "chromosome"
}
Schema
{
"data": {
"links": [
{
"types": [
"string"
],
"action": "string",
"href": "string",
"rel": "string"
}
],
"accession": "string",
"level": "string"
},
"links": [
{
"rel": "string",
"types": [
"string"
],
"action": "string",
"href": "string"
}
]
}
Code
Description
200
OK
400
Bad Request
404
Not Found
406
Not Acceptable
500
Internal Server Error
503
Service Unavailable
Taxon
GET
/taxa
Get basic taxon data for taxa with the given name
Description
Get basic taxon data for taxa with the given name
Path Parameters
None
Query Parameters
Name
name
Description
Name or pattern of the taxa
Type
string
Required
true
Example
homo sapiens/
Name
scientific
Description
Whether to search in scientific names only
Type
boolean
Required
false
Name
exact
Description
Whether to search for exactly that name or use the name as a pattern
Type
boolean
Required
false
Name
offset
Description
Offset of entries when retrieving lists
Type
integer
Required
false
Extra
Minimum: 0, Default: 0
Example
0
Name
limit
Description
Amount of entries per response
Type
integer
Required
false
Extra
Minimum: -1, Default: -1
Example
20
Name
field_composite
Description
Determines fields for the return type
Type
string
Required
false
Extra
Default: default
Name
plain_data
Description
Reduce response to the data property and remove all hyper refereces
Type
boolean
Required
false
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
[
{
"name": "Homo sapiens/Mus musculus xenograft",
"parent": 1002697,
"tax_id": 1383439
},
{
"name": "Homo sapiens/Rattus norvegicus xenograft",
"parent": 1002697,
"tax_id": 1573476
}
]
Schema
{
"data": [
{
"common_name": "string",
"links": [
{
"action": "string",
"href": "string",
"rel": "string",
"types": [
"string"
]
}
],
"name": "string",
"parent": "integer",
"tax-id": "integer"
}
],
"links": [
{
"href": "string",
"rel": "string",
"types": [
"string"
],
"action": "string"
}
]
}
Code
Description
200
OK
400
Bad Request
404
Not Found
406
Not Acceptable
500
Internal Server Error
503
Service Unavailable
GET
/taxa/{taxon_id}
Get information about a specific taxon
Description
Get information about a specific taxon
Path Parameters
Name
taxon_id
Description
id of taxon
Type
integer
Required
true
Example
9606
Query Parameters
Name
field_composite
Description
Determines fields for the return type
Type
string
Required
false
Extra
Default: default
Name
plain_data
Description
Reduce response to the data property and remove all hyper refereces
Type
boolean
Required
false
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
{
"common_name": "human",
"name": "Homo sapiens",
"parent": 9605,
"tax_id": 9606
}
Schema
{
"data": {
"parent": "integer",
"tax-id": "integer",
"common_name": "string",
"links": [
{
"action": "string",
"href": "string",
"rel": "string",
"types": [
"string"
]
}
],
"name": "string"
},
"links": [
{
"action": "string",
"href": "string",
"rel": "string",
"types": [
"string"
]
}
]
}
Code
Description
200
OK
400
Bad Request
404
Not Found
406
Not Acceptable
500
Internal Server Error
503
Service Unavailable
GET
/taxa/{taxon_id}/children
Get the children of a taxon given its id
Description
Get the children of a taxon given its id
Path Parameters
Name
taxon_id
Description
id of taxon
Type
integer
Required
true
Example
9606
Query Parameters
Name
offset
Description
Offset of entries when retrieving lists
Type
integer
Required
false
Extra
Minimum: 0, Default: 0
Example
0
Name
limit
Description
Amount of entries per response
Type
integer
Required
false
Extra
Minimum: -1, Default: -1
Example
20
Name
field_composite
Description
Determines fields for the return type
Type
string
Required
false
Extra
Default: default
Name
plain_data
Description
Reduce response to the data property and remove all hyper refereces
Type
boolean
Required
false
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
[
{
"common_name": "Denisova hominin",
"name": "Homo sapiens subsp. 'Denisova'",
"parent": 9606,
"tax_id": 741158
},
{
"common_name": "Neandertal",
"name": "Homo sapiens neanderthalensis",
"parent": 9606,
"tax_id": 63221
}
]
Schema
{
"data": [
{
"common_name": "string",
"links": [
{
"action": "string",
"href": "string",
"rel": "string",
"types": [
"string"
]
}
],
"name": "string",
"parent": "integer",
"tax-id": "integer"
}
],
"links": [
{
"action": "string",
"href": "string",
"rel": "string",
"types": [
"string"
]
}
]
}
Code
Description
200
OK
400
Bad Request
404
Not Found
406
Not Acceptable
500
Internal Server Error
503
Service Unavailable
GET
/taxa/{taxon_id}/parent
Get the parent's taxon id of a given taxon
Description
Get the parent's taxon id of a given taxon
Path Parameters
Name
taxon_id
Description
id of taxon
Type
integer
Required
true
Example
9606
Query Parameters
Name
field_composite
Description
Determines fields for the return type
Type
string
Required
false
Extra
Default: default
Name
plain_data
Description
Reduce response to the data property and remove all hyper refereces
Type
boolean
Required
false
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
{
"name": "Homo",
"parent": 207598,
"tax_id": 9605
}
Schema
{
"data": {
"links": [
{
"rel": "string",
"types": [
"string"
],
"action": "string",
"href": "string"
}
],
"name": "string",
"parent": "integer",
"tax-id": "integer",
"common_name": "string"
},
"links": [
{
"action": "string",
"href": "string",
"rel": "string",
"types": [
"string"
]
}
]
}
Code
Description
200
OK
400
Bad Request
404
Not Found
406
Not Acceptable
500
Internal Server Error
503
Service Unavailable
GET
/taxa/{taxon_id}/subtree
Get the subtree of a taxon including itself
Description
Get the subtree of a taxon including itself
Path Parameters
Name
taxon_id
Description
id of taxon
Type
integer
Required
true
Example
9606
Query Parameters
Name
offset
Description
Offset of entries when retrieving lists
Type
integer
Required
false
Extra
Minimum: 0, Default: 0
Example
0
Name
limit
Description
Amount of entries per response
Type
integer
Required
false
Extra
Minimum: -1, Default: -1
Example
20
Name
field_composite
Description
Determines fields for the return type
Type
string
Required
false
Extra
Default: default
Name
plain_data
Description
Reduce response to the data property and remove all hyper refereces
Type
boolean
Required
false
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
[
{
"common_name": "human",
"name": "Homo sapiens",
"parent": 9605,
"tax_id": 9606
},
{
"common_name": "Denisova hominin",
"name": "Homo sapiens subsp. 'Denisova'",
"parent": 9606,
"tax_id": 741158
},
{
"common_name": "Neandertal",
"name": "Homo sapiens neanderthalensis",
"parent": 9606,
"tax_id": 63221
}
]
Schema
{
"data": [
{
"parent": "integer",
"tax-id": "integer",
"common_name": "string",
"links": [
{
"action": "string",
"href": "string",
"rel": "string",
"types": [
"string"
]
}
],
"name": "string"
}
],
"links": [
{
"href": "string",
"rel": "string",
"types": [
"string"
],
"action": "string"
}
]
}
Code
Description
200
OK
400
Bad Request
404
Not Found
406
Not Acceptable
500
Internal Server Error
503
Service Unavailable
GET
/taxonomy
Get subservices of the taxonomy path
Description
Get subservices of the taxonomy path
Path Parameters
None
Query Parameters
None
{
"links": [
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy",
"rel": "self",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/accessions",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "POST",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/fintac",
"rel": "service",
"types": [
"text/plain;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/mrca",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "POST",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/neighbors",
"rel": "service",
"types": [
"text/plain;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/path",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
}
]
}
Schema
{
"links": [
{
"action": "string",
"href": "string",
"rel": "string",
"types": [
"string"
]
}
]
}
Code
Description
200
OK
GET
/taxonomy/accessions
Get the recursive accessions for a list of taxa
Description
Get the recursive accessions for a list of taxa
Path Parameters
None
Query Parameters
Name
field_composite
Description
Determines fields for the return type
Type
string
Required
false
Extra
Default: default
Name
taxon_ids
Description
Ids of taxa for finding accessions
Type
integer[]
Required
true
Example
278148,602633
Name
plain_data
Description
Reduce response to the data property and remove all hyper refereces
Type
boolean
Required
false
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
[
{
"accessions": [
{
"accession": "GCF_001618845.1",
"level": "complete"
}
],
"tax_id": 278148
},
{
"accessions": [
{
"accession": "GCA_003063835.1",
"level": "scaffold"
}
],
"tax_id": 602633
},
{
"accessions": [
{
"accession": "GCF_000185905.1",
"level": "complete"
}
],
"tax_id": 765698
}
]
Schema
{
"data": [
{
"links": [
{
"action": "string",
"href": "string",
"rel": "string",
"types": [
"string"
]
}
],
"tax_id": "integer",
"accessions": [
{
"accession": "string",
"level": "string",
"links": [
{
"rel": "string",
"types": [
"string"
],
"action": "string",
"href": "string"
}
]
}
]
}
],
"links": [
{
"action": "string",
"href": "string",
"rel": "string",
"types": [
"string"
]
}
]
}
Code
Description
200
OK
400
Bad Request
404
Not Found
406
Not Acceptable
500
Internal Server Error
503
Service Unavailable
GET
/taxonomy/mrca
Get the most recent common ancestor of a list of taxa
Description
Get the most recent common ancestor of a list of taxa
Path Parameters
None
Query Parameters
Name
field_composite
Description
Determines fields for the return type
Type
string
Required
false
Extra
Default: default
Name
taxon_ids
Description
Ids of taxa for which to find the mrca
Type
integer[]
Required
true
Example
9606,741158,63221
Name
plain_data
Description
Reduce response to the data property and remove all hyper refereces
Type
boolean
Required
false
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
{
"common_name": "human",
"name": "Homo sapiens",
"parent": 9605,
"tax_id": 9606
}
Schema
{
"data": {
"common_name": "string",
"links": [
{
"types": [
"string"
],
"action": "string",
"href": "string",
"rel": "string"
}
],
"name": "string",
"parent": "integer",
"tax-id": "integer"
},
"links": [
{
"types": [
"string"
],
"action": "string",
"href": "string",
"rel": "string"
}
]
}
Code
Description
200
OK
400
Bad Request
404
Not Found
406
Not Acceptable
500
Internal Server Error
503
Service Unavailable
GET
/taxonomy/path
Get the path between a start taxon, that is further from the root and an end taxon that is closer to the root. Returns an empty list if no path connects start and end
Description
Get the path between a start taxon, that is further from the root and an end taxon that is closer to the root. Returns an empty list if no path connects start and end
Path Parameters
None
Query Parameters
Name
offset
Description
Offset of entries when retrieving lists
Type
integer
Required
false
Extra
Minimum: 0, Default: 0
Example
0
Name
limit
Description
Amount of entries per response
Type
integer
Required
false
Extra
Minimum: -1, Default: -1
Example
20
Name
field_composite
Description
Determines fields for the return type
Type
string
Required
false
Extra
Default: default
Name
start_id
Description
Id of start taxon, further from root
Type
integer
Required
true
Example
9606
Name
end_id
Description
Id of end taxon, closer to root
Type
integer
Required
true
Example
40674
Name
plain_data
Description
Reduce response to the data property and remove all hyper refereces
Type
boolean
Required
false
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
[
{
"name": "Homo",
"parent": 207598,
"tax_id": 9605
},
{
"name": "Homininae",
"parent": 9604,
"tax_id": 207598
},
{
"common_name": "great apes",
"name": "Hominidae",
"parent": 314295,
"tax_id": 9604
},
{
"common_name": "apes",
"name": "Hominoidea",
"parent": 9526,
"tax_id": 314295
},
{
"name": "Catarrhini",
"parent": 314293,
"tax_id": 9526
},
{
"name": "Simiiformes",
"parent": 376913,
"tax_id": 314293
},
{
"name": "Haplorrhini",
"parent": 9443,
"tax_id": 376913
},
{
"common_name": "primates",
"name": "Primates",
"parent": 314146,
"tax_id": 9443
},
{
"name": "Euarchontoglires",
"parent": 1437010,
"tax_id": 314146
},
{
"name": "Boreoeutheria",
"parent": 9347,
"tax_id": 1437010
},
{
"common_name": "placentals",
"name": "Eutheria",
"parent": 32525,
"tax_id": 9347
},
{
"name": "Theria",
"parent": 40674,
"tax_id": 32525
},
{
"common_name": "mammals",
"name": "Mammalia",
"parent": 32524,
"tax_id": 40674
}
]
Schema
{
"data": [
{
"links": [
{
"href": "string",
"rel": "string",
"types": [
"string"
],
"action": "string"
}
],
"name": "string",
"parent": "integer",
"tax-id": "integer",
"common_name": "string"
}
],
"links": [
{
"action": "string",
"href": "string",
"rel": "string",
"types": [
"string"
]
}
]
}
Code
Description
200
OK
400
Bad Request
404
Not Found
406
Not Acceptable
500
Internal Server Error
503
Service Unavailable
Program
GET
/programs
Get subservices of the programs path
Description
Get subservices of the programs path
Path Parameters
None
Query Parameters
None
{
"links": [
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy",
"rel": "self",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/accessions",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "POST",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/fintac",
"rel": "service",
"types": [
"text/plain;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/mrca",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "POST",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/neighbors",
"rel": "service",
"types": [
"text/plain;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/path",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
}
]
}
Schema
{
"links": [
{
"href": "string",
"rel": "string",
"types": [
"string"
],
"action": "string"
}
]
}
Code
Description
200
OK
GET
/programs/ants
Executes the neighbors program ants remotely
Description
Executes the neighbors program ants remotely
Path Parameters
None
Query Parameters
Name
options
Description
Program options
Type
string[]
Required
false
Example
9606
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
# Back ID Name Rank 31 1 root no rank 30 131567 cellular organisms cellular root 29 2759 Eukaryota domain 28 33154 Opisthokonta clade 27 33208 Metazoa kingdom 26 6072 Eumetazoa clade 25 33213 Bilateria clade 24 33511 Deuterostomia clade 23 7711 Chordata phylum 22 89593 Craniata subphylum 21 7742 Vertebrata clade 20 7776 Gnathostomata clade 19 117570 Teleostomi clade 18 117571 Euteleostomi clade 17 8287 Sarcopterygii superclass 16 1338369 Dipnotetrapodomorpha clade 15 32523 Tetrapoda clade 14 32524 Amniota clade 13 40674 Mammalia class 12 32525 Theria clade 11 9347 Eutheria clade 10 1437010 Boreoeutheria clade 9 314146 Euarchontoglires superorder 8 9443 Primates order 7 376913 Haplorrhini suborder 6 314293 Simiiformes infraorder 5 9526 Catarrhini parvorder 4 314295 Hominoidea superfamily 3 9604 Hominidae family 2 207598 Homininae subfamily 1 9605 Homo genus 0 9606 Homo sapiens species"
Schema
"string"
Code
Description
200
OK
404
Not Found
500
Internal Server Error
503
Service Unavailable
GET
/programs/dree
Executes the neighbors program dree remotely
Description
Executes the neighbors program dree remotely
Path Parameters
None
Query Parameters
Name
options
Description
Program options
Type
string[]
Required
false
Example
-n,-g,207598
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
digraph g {
rankdir=LR
9592 [label="9592"]
9592 [label="Gorilla"]
207598 -> 9592
9593 [color="lightsalmon",style=filled]
9593 [label="Gorilla gorilla"]
9592 -> 9593
9595 [color="lightsalmon",style=filled]
9595 [label="Gorilla gorilla gorilla"]
9593 -> 9595
9596 [label="9596"]
9596 [label="Pan"]
207598 -> 9596
9597 [color="lightsalmon",style=filled]
9597 [label="Pan paniscus"]
9596 -> 9597
9598 [color="lightsalmon",style=filled]
9598 [label="Pan troglodytes"]
9596 -> 9598
9605 [label="9605"]
9605 [label="Homo"]
207598 -> 9605
9606 [color="lightsalmon",style=filled]
9606 [label="Homo sapiens"]
9605 -> 9606
37012 [color="lightsalmon",style=filled]
37012 [label="Pan troglodytes verus"]
9598 -> 37012
207598 [label="207598"]
207598 [label="Homininae"]
499232 [color="lightsalmon",style=filled]
499232 [label="Gorilla beringei"]
9592 -> 499232
1159185 [color="lightsalmon",style=filled]
1159185 [label="Gorilla beringei beringei"]
499232 -> 1159185}"
Schema
"string"
Code
Description
200
OK
404
Not Found
500
Internal Server Error
503
Service Unavailable
POST
/programs/fintac
Executes the neighbors program fintac remotely
Description
Executes the neighbors program fintac remotely
Path Parameters
None
Query Parameters
Name
options
Description
Program options
Type
string[]
Required
false
Example
-t,991910_,-u,562_
Name
extra
Description
Names of files. These need to match the filenames of the multipart/form-data exactly
Type
string[]
Required
false
Example
eco7k.nwk
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
Request Body
Content-Type
multipart/form-data
Description
The request body provides the files named in the query parameters. It is essential, that the files' names given in the request body and in the query match.
#Clade Targets Neighbors Unknowns Split (%) Parent Dist(Parent) 5007 22 8 18 98.53 5005 0.000385"
Schema
"string"
Code
Description
200
OK
404
Not Found
500
Internal Server Error
503
Service Unavailable
GET
/programs/neighbors
Executes the program neighbors remotely
Description
Executes the program neighbors remotely
Path Parameters
None
Query Parameters
Name
options
Description
Program options
Type
string[]
Required
false
Example
-L,complete,-t,9606
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
# MRCA(targets): 9606, Homo sapiens # MRCA(targets+neighbors): 9605, Homo # Type Taxon-ID Name Genomes t 9606 Homo sapiens GCA_947361175.1|GCA_963931935.1|GCF_009914755.1 tt 63221 Homo sapiens neanderthalensis - tt 741158 Homo sapiens subsp. 'Denisova' - n 1425170 Homo heidelbergensis - n 2665952 environmental samples - n 2665953 Homo sapiens environmental sample - n 2813598 unclassified Homo - n 2813599 Homo sp. -"
Schema
"string"
Code
Description
200
OK
404
Not Found
500
Internal Server Error
503
Service Unavailable
POST
/programs/neighbors
Executes the program neighbors remotely with one or more files of target taxa
Description
Executes the program neighbors remotely with one or more files of target taxa
Path Parameters
None
Query Parameters
Name
options
Description
Program options
Type
string[]
Required
false
Example
-L,complete
Name
extra
Description
Names of files
Type
string[]
Required
false
Example
targets.txt
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
Request Body
Content-Type
multipart/form-data
Description
The request body provides the files named in the query parameters. It is essential, that the files' names given in the request body and in the query match.
# MRCA(targets): 9606, Homo sapiens # MRCA(targets+neighbors): 9605, Homo # Type Taxon-ID Name Genomes t 9606 Homo sapiens GCA_947361175.1|GCA_963931935.1|GCF_009914755.1 tt 63221 Homo sapiens neanderthalensis - tt 741158 Homo sapiens subsp. 'Denisova' - n 1425170 Homo heidelbergensis - n 2665952 environmental samples - n 2665953 Homo sapiens environmental sample - n 2813598 unclassified Homo - n 2813599 Homo sp. -"
Schema
"string"
Code
Description
200
OK
404
Not Found
500
Internal Server Error
503
Service Unavailable
GET
/programs/ranks
Executes the neighbors program ranks remotely
Description
Executes the neighbors program ranks remotely
Path Parameters
None
Query Parameters
Name
options
Description
Program options
Type
string[]
Required
false
Example
562
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
digraph g {
rankdir=LR
1 [label="species\n392350 (97.7%)"]
2 [label="no rank\n4503 (1.1%)"]
3 [label="no rank\n17 (< 0.1%)"]
4 [label="strain\n422 (0.1%)"]
5 [label="no rank\n2 (< 0.1%)"]
6 [label="serogroup\n1646 (0.4%)"]
7 [label="no rank\n15 (< 0.1%)"]
8 [label="serotype\n6 (< 0.1%)"]
9 [label="strain\n1 (< 0.1%)"]
10 [label="strain\n12 (< 0.1%)"]
11 [label="serotype\n30 (< 0.1%)"]
12 [label="strain\n1 (< 0.1%)"]
13 [label="strain\n2438 (0.6%)"]
14 [label="no rank\n85 (< 0.1%)"]
1 -> 2
2 -> 3
2 -> 4
4 -> 5
1 -> 6
6 -> 7
6 -> 8
8 -> 9
6 -> 10
1 -> 11
11 -> 12
1 -> 13
13 -> 14
}"
Schema
"string"
Code
Description
200
OK
404
Not Found
500
Internal Server Error
503
Service Unavailable
POST
/programs/ranks
Executes the neighbors program ranks remotely with one file of genome accessions
Description
Executes the neighbors program ranks remotely with one file of genome accessions
Path Parameters
None
Query Parameters
Name
options
Description
Program options
Type
string[]
Required
false
Example
-g,myGenomeList.txt,562
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
Request Body
Content-Type
multipart/form-data
Description
The request body provides the files named in the query parameters. It is essential, that the files' names given in the request body and in the query match.
digraph g {
rankdir=LR
1 [label="species\n392350 (97.7%)"]
2 [label="no rank\n4503 (1.1%)"]
3 [label="no rank\n17 (< 0.1%)"]
4 [label="strain\n422 (0.1%)"]
5 [label="no rank\n2 (< 0.1%)"]
6 [label="serogroup\n1646 (0.4%)"]
7 [label="no rank\n15 (< 0.1%)"]
8 [label="serotype\n6 (< 0.1%)"]
9 [label="strain\n1 (< 0.1%)"]
10 [label="strain\n12 (< 0.1%)"]
11 [label="serotype\n30 (< 0.1%)"]
12 [label="strain\n1 (< 0.1%)"]
13 [label="strain\n2438 (0.6%)"]
14 [label="no rank\n85 (< 0.1%)"]
1 -> 2
2 -> 3
2 -> 4
4 -> 5
1 -> 6
6 -> 7
6 -> 8
8 -> 9
6 -> 10
1 -> 11
11 -> 12
1 -> 13
13 -> 14
}"
Schema
"string"
Code
Description
200
OK
404
Not Found
500
Internal Server Error
503
Service Unavailable
GET
/programs/taxi
Executes the neighbors program taxi remotely
Description
Executes the neighbors program taxi remotely
Path Parameters
None
Query Parameters
Name
options
Description
Program options
Type
string[]
Required
false
Example
-t,9606
Name
db
Description
Defines which database should be queried
Type
string
Required
false
Extra
Default: latest
# ID Parent Name 9606 9605 Homo sapiens"
Schema
"string"
Code
Description
200
OK
404
Not Found
500
Internal Server Error
503
Service Unavailable
Miscellaneous
GET
/
Get a list of the api's services
Description
Get a list of the api's services
Path Parameters
None
Query Parameters
None
{
"links": [
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2",
"rel": "self",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/accessions",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/accessions/{accession_id}",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxa",
"rel": "service",
"types": [
"application/json;charset=utf-8",
"text/plain;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxa/{taxon_id}",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxa/{taxon_id}/ancestors",
"rel": "service",
"types": [
"text/plain;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxa/{taxon_id}/children",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxa/{taxon_id}/parent",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "POST",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxa/{taxon_id}/rank_distribution",
"rel": "service",
"types": [
"text/vnd.graphviz;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxa/{taxon_id}/subtree",
"rel": "service",
"types": [
"application/json;charset=utf-8",
"text/vnd.graphviz;charset=utf-8",
"text/plain;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/accessions",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "POST",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/fintac",
"rel": "service",
"types": [
"text/plain;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/mrca",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
},
{
"action": "POST",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/neighbors",
"rel": "service",
"types": [
"text/plain;charset=utf-8"
]
},
{
"action": "GET",
"href": "https://neighbors.evolbio.mpg.de/api/v2/taxonomy/path",
"rel": "service",
"types": [
"application/json;charset=utf-8"
]
}
]
}
Schema
{
"links": [
{
"rel": "string",
"types": [
"string"
],
"action": "string",
"href": "string"
}
]
}
Code
Description
200
OK
GET
/databases
Get active databases
Description
Get active databases
Path Parameters
None
Query Parameters
Name
plain_data
Description
Reduce response to the data property and remove all hyper refereces
Type
boolean
Required
false
Name
limit
Description
Amount of entries per response
Type
integer
Required
false
Extra
Minimum: -1, Default: -1
Example
20
Name
offset
Description
Offset of entries when retrieving lists
Type
integer
Required
false
Extra
Minimum: 0, Default: 0
Example
0
[ "latest", "2026-07", "2026-06" ]
Schema
[ "string" ]
Code
Description
200
OK