- The base URL of the API is https://versologie.cz/poetree/api/
- All response bodies are JSON encoded (UTF-8)
- HTTP method: GET
- PoeTree API employs a relational database. It thus employs an integer identifiers different from those used in JSON files. While the former is denoted as id_ when used as a primary key or as id_{table_name} when used as a foreign key, the original JSON identifiers are kept under id key
- If using PoeTree data in your research, please see
how to cite
▼
corpora
https://versologie.cz/poetree/api/corpora
Return the list of available corpora and their basic characteristics (# of authors, # of poems...).
The response is a JSON of the following structure:
[
{
"corpus": (str) ISO code of corpus language,
"desc": (str) Description of corpus,
"n_authors": (int) # of authors,
"n_poems": (int) # of poems,
"n_lines": (int) # of lines,
"n_types": (int) # of types,
"n_tokens": (int) # of tokens
}
]
Example: List all available corpora.
show 
https://versologie.cz/poetree/api/corpora▼
corpus
https://versologie.cz/poetree/api/corpus
Return the metadata on a single corpus (# of authors, # of poems...).
| Parameter | Mandatory | Data type | Description |
| corpus | 1 | str | Corpus to get metadata of |
The response is a JSON of the following structure:
{
"corpus": (str) ISO code of corpus language,
"desc": (str) Description of corpus,
"n_authors": (int) # of authors,
"n_poems": (int) # of poems,
"n_lines": (int) # of lines,
"n_types": (int) # of types,
"n_tokens": (int) # of tokens
}
Example: Get metadata on PoeTree.fr
show
https://versologie.cz/poetree/api/corpus?corpus=fr▼
authors
https://versologie.cz/poetree/api/authors
Return the list of authors and their metadata in a particular corpus.
| Parameter | Mandatory | Data type | Description |
| corpus | 1 | str | Corpus to scan |
| country | 0 | str | Limit to authors from certain countries. Either single value (country=pt) or stringified list (country=pt,br) |
| born_after | 0 | int | Limit to authors born no sooner than a given year |
| born_before | 0 | int | Limit to authors born no later than a given year |
| died_after | 0 | int | Limit to authors that died no sooner than a given year |
| died_before | 0 | int | Limit to authors that died no later than a given year |
The response is a JSON of the following structure:
[
{
"id_": (int) id(DB) of author",
"name": (str) name of author author.name,
"viaf": (str|null) VIAF id author.viaf,
"wiki": (str|null) wikidata id author.wiki,
"country": (str|null) country iso code if relevant author.country,
"born": (int|null) year of birth author.born,
"died": (int|null) year of death author.died,
"n_poems": (int) number of poems by author
}
]
,
"viaf": (str|null) VIAF id author.viaf,
"wiki": (str|null) wikidata id author.wiki,
"country": (str|null) country iso code if relevant author.country,
"born": (int|null) year of birth author.born,
"died": (int|null) year of death author.died,
"n_poems": (int) number of poems by author
}
]Example: Authors in PoeTree.en coming from uk and born no sooner than 1800
show
https://versologie.cz/poetree/api/authors?corpus=en&country=uk&born_after=1800▼
author
https://versologie.cz/poetree/api/author
Return data on a single author. One of (id_author, wiki, viaf) parameters has to be set.
| Parameter | Mandatory | Data type | Description |
| corpus | 1 | str | Corpus to scan |
| id_author | 0 | str | Author's id(DB) |
| wiki | 0 | int | Author's wiki id |
| viaf | 0 | int | Author's viaf id |
The response is a JSON of the following structure:
{
"id_": (int) id(DB) of author",
"name": (str) name of author author.name,
"viaf": (str|null) VIAF id author.viaf,
"wiki": (str|null) wikidata id author.wiki,
"country": (str|null) country iso code if relevant author.country,
"born": (int|null) year of birth author.born,
"died": (int|null) year of death author.died,
"n_poems": (int) number of poems by author
}
,
"viaf": (str|null) VIAF id author.viaf,
"wiki": (str|null) wikidata id author.wiki,
"country": (str|null) country iso code if relevant author.country,
"born": (int|null) year of birth author.born,
"died": (int|null) year of death author.died,
"n_poems": (int) number of poems by author
}Example: Author in PoeTree.en having id_author 1
show
https://versologie.cz/poetree/api/author?corpus=en&id_author=1▼
sources
https://versologie.cz/poetree/api/sources
Return the list of sources (books).
| Parameter | Mandatory | Data type | Description |
| corpus | 1 | str | Corpus to scan |
| id_author | 0 | int | Author of the source id(DB) |
| wiki | 0 | str | Author of the source wiki id |
| viaf | 0 | str | Author of the source viaf id |
| published_before | 0 | int | Limit to sources published no sooner than a given year |
| published_after | 0 | int | Limit to sources published no later than a given year |
The response is a JSON of the following structure:
[
{
"id_": (int) id(DB) of source,
"id": (str) id(JSON) of source source.id,
"title": (str|null) title of source source.title,
"id_author": (int|list) id(DB) of source author(s),
"year_published": (int|null) year when source published source.year_published,
"publisher": (str|null) name of publisher source.publisher,
"place": (int|null) place where published source.place
}
]
,
"title": (str|null) title of source source.title,
"id_author": (int|list) id(DB) of source author(s),
"year_published": (int|null) year when source published source.year_published,
"publisher": (str|null) name of publisher source.publisher,
"place": (int|null) place where published source.place
}
]Example: Poems from PoeTree.cs written by an author with wiki id Q712420 (Otokar Březina)
show
https://versologie.cz/poetree/api/sources?corpus=cs&wiki=Q712420▼
source
https://versologie.cz/poetree/api/source
Return object representing a single source. One of the (id_source, id_poem) parameters has to be specified.
| Parameter | Mandatory | Data type | Description |
| corpus | 1 | str | Corpus to scan |
| id_source | 0 | int | Id(DB) of the source |
| id_poem | 0 | int | Id(DB) of the poem its source is to be found |
The response is a JSON of the following structure:
{
"id_": (int) id(DB) of source,
"id": (str) id(JSON) of source source.id,
"title": (str|null) title of source source.title,
"id_author": (int|list) id(DB) of source author(s),
"year_published": (int|null) year when source published source.year_published,
"publisher": (str|null) name of publisher source.publisher,
"place": (int|null) place where published source.place
}
,
"title": (str|null) title of source source.title,
"id_author": (int|list) id(DB) of source author(s),
"year_published": (int|null) year when source published source.year_published,
"publisher": (str|null) name of publisher source.publisher,
"place": (int|null) place where published source.place
}Example: Source of the poem having id=1 in PoeTree.en
show
https://versologie.cz/poetree/api/source?corpus=en&id_poem=1▼
poems
https://versologie.cz/poetree/api/poems
Return the list of poems written by selected author / coming from selected source and their metadata. One of (id_author, wiki, viaf, id_source) parameters has to be set.
| Parameter | Mandatory | Data type | Description |
| corpus | 1 | str | Corpus to scan |
| id_author | 0 | int | Author's id(DB) |
| wiki | 0 | str | Author's wiki id |
| viaf | 0 | str | Author's viaf id |
| id_source | 0 | str | Id(DB) of the source |
The response is a JSON of the following structure:
[
{
"id_": (int) id(DB) of poem,
"id": (str) id(JSON) of poem id,
"title": (str) title of poem title,
"id_source": (str) id(DB) of source,
"id_author": (int|list) id(DB) of author(s),
"year_created_from": (int|null) min year of creation year_created,
"year_created_to": (int|null) max year of creation year_created,
"duplicate": (false|str) whether considered duplicate duplicate,
}
]
,
"title": (str) title of poem title,
"id_source": (str) id(DB) of source,
"id_author": (int|list) id(DB) of author(s),
"year_created_from": (int|null) min year of creation year_created,
"year_created_to": (int|null) max year of creation year_created,
"duplicate": (false|str) whether considered duplicate duplicate,
}
]Example: Poems from PoeTree.es written by an author with wiki id Q165257 (Lope de Vega)
show
https://versologie.cz/poetree/api/poems?corpus=es&wiki=Q165257▼
poem
https://versologie.cz/poetree/api/poem
Return object representing a single poem
| Parameter | Mandatory | Data type | Description |
| corpus | 1 | str | Corpus to scan |
| id_poem | 1 | int | Id(DB) of the poem |
| neighbors | 0 | bool | Whether to include list of nearest neighbors (default: 0) |
| lines | 0 | bool | Whether to include object representing lines (default: 1) |
| words | 0 | bool | Whether to include objects representing words (default: 1) |
| multiwords | 0 | bool | Whether to return multiwords or their parts separately (default: 0) |
The response is a JSON of the following structure:
{
"id_": (int) id(DB) of poem,
"id": (int) id(JSON) of poem id,
"title": (str) title of poem title,
"id_source": (int) id(DB) of source,
"id_author": (int|list) id(DB) of author(s),
"year_created_from": (int|null) min year of creation year_created,
"year_created_to": (int|null) max year of creation year_created,
"duplicate": (false|str) whether considered duplicate duplicate,
"neighbors": (list) list of 20 nearest neighbors neighbors,
"body": (list) list representing lines, words... body
}
,
"title": (str) title of poem title,
"id_source": (int) id(DB) of source,
"id_author": (int|list) id(DB) of author(s),
"year_created_from": (int|null) min year of creation year_created,
"year_created_to": (int|null) max year of creation year_created,
"duplicate": (false|str) whether considered duplicate duplicate,
"neighbors": (list) list of 20 nearest neighbors neighbors,
"body": (list) list representing lines, words... body
}Example: Poem from PoeTree.cs having id_poem=1 without word annotation
show
https://versologie.cz/poetree/api/poem?corpus=cs&id_poem=1&words=0▼
countries
https://versologie.cz/poetree/api/countries
Returns country codes that appear in the corpus and number of authors per country
| Parameter | Mandatory | Data type | Description |
| corpus | 1 | str | Corpus to scan |
The response is a JSON of the following structure:
{
"{iso-code of country}author.country": (int) number of authors
}
": (int) number of authors
}Example: Country codes appearing in PoeTree.en
show
https://versologie.cz/poetree/api/countries?corpus=enSupported by the Czech Science Foundation (GA23-07727S)