API documentation
Overview
DISHAS API is available at the URL https://dishas.obspm.fr/elastic-query: it offers a fast access to DISHAS's raw data with advanced search functionalities. It relies for now on the elasticsearch query language expressed in a JSON format. Only public data are accessible; draft won't appear in the results.
All main entities of DISHAS database are queryable. They correspond to an elasticsearch index:
| Entity name | Index name | Structure | ||||
|---|---|---|---|---|---|---|
| Table edition | edited_text | # | ||||
| Table content | table_content | # | ||||
| Table witness | original_text | # | ||||
| Primary source | primary_source | # | ||||
| Work | work | # | ||||
| Parameter set | parameter_set | # | ||||
| Formula definition | formula_definition | # | ||||
Each index is structured according to a particular mapping that defines where each metadata is accessible in the JSON object representing the entity. For more details on how metadata fields are defined for each index, see the "Data structure" section.
The URL of the API admits 6 arguments (optional or mandatory) that define the query that will be sent to the elasticsearch database.
| Argument | Description | Value | |||
|---|---|---|---|---|---|
| index | Mandatory: the index that is going to be queried. It is not now possible to perform cross-index queries. | Index name | |||
| query | The query in itself restricting the number records of the chosen index that will be returned. The query must be formulated in the elasticsearch query language. For examples, see the corresponding section. No query means all records will be returned. | JSON query | |||
| source | Defines the fields of metadata that are going to appear in the results. For example, if only identifiers are needed, ["id"] can be provided as source. | Array | |||
| hits | If set to true, the result object will only contain the array of matching records, without the header of every elasticsearch query. | Boolean value | |||
| size | Maximum number of records contained in the result object (by default, set to 10. Maximal value: 200) | Number | |||
| from | Defines the offset from the first result you want to fetch (by default, set to0). Useful in case there is more than 200 matching records. | Number | |||
Examples
List all records
Endpoint to retrieve a list of all records of a given entity (e.g.: all primary sources)
https://dishas.obspm.fr/elastic-query?index=primary_source
{
"took":1,
"timed_out":false,
"_shards":{
"total":5,
"successful":5,
"skipped":0,
"failed":0
},
"hits":{
"total":13,
"max_score":1.0,
"hits":[
{"_index":"primary_source",
"_type":"primary_source",
"_id":"5",
"_score":1.0,
"_source":{
"id":"5",
"prim_type":"ep",
"digital_identifier":null,
"prim_title":"Tabule astronomice illustrissimi Alfonsii regis Castelle",
"prim_title_original_char":null,
"date":"1483",
"library":{
"kibana_name":"London, Royaume-Uni, The British Library",
"kibana_id":"Library6"
},
"kibana_name":"London, The British Library | 000061853, Tabule astronomice illustrissimi Alfonsii regis Castelle, E. Ratdolt, 1483",
"default_title":"000061853 | The British Library",
"kibana_id":"PrimarySource5",
"original_texts":[ ... ],
"tpq":null,
"taq":null,
"tpq_date":null,
"taq_date":null,
"places":[ ... ]
}
}, { ... }
}
Show only hits
To retrieve only the results of the query, add &hits=true in the arguments of the URL.
https://dishas.obspm.fr/elastic-query?index=primary_source&hits=true
[
{
"id":"5",
"prim_type":"ep",
"digital_identifier":null,
"prim_title":"Tabule astronomice illustrissimi Alfonsii regis Castelle",
"prim_title_original_char":null,
"date":"1483",
"library":{
"kibana_name":"London, Royaume-Uni, The British Library",
"kibana_id":"Library6"
},
"kibana_name":"London, The British Library | 000061853, Tabule astronomice illustrissimi Alfonsii regis Castelle, E. Ratdolt, 1483",
"default_title":"000061853 | The British Library",
"kibana_id":"PrimarySource5",
"original_texts":[ ... ],
"tpq":null,
"taq":null,
"tpq_date":null,
"taq_date":null,
"places":[ ... ]
}, { ... }
]
Show only certain fields
To retrieve only certain fields of metadata, add the array of fields you want to appear to the source argument of the URL (e.g. show only the the identifiers of work and the name of their creators).
https://dishas.obspm.fr/elastic-query?index=work&hits=true&source=["id","historical_actors.kibana_name"]
[
{
"historical_actors":[
{
"kibana_name":"John of Saxony (1327-1335)"
}
],
"id":"5"
},
{
"historical_actors":[
{
"kibana_name":"Martín Cortés de Albacar (1510–1582)"
}
],
"id":"8"
},
{
"historical_actors":[
{
"kibana_name":"John of Genoa (1320-1337)"
}
],
"id":"4"
},
{
"historical_actors":[
{
"kibana_name":"John of Lignières (1290-1350)"
}
],
"id":"6"
},
{
"historical_actors":[
{
"kibana_name":"John of Lignières (1290-1350)"
}
],
"id":"7"
}
]
Find specific resources
To search for specific resources, any elasticsearch query can be passed to the query argument of the URL (e.g. find the work titled "Table of 1322").
https://dishas.obspm.fr/elastic-query?index=work&hits=true&source=["id","title"]&query={"match":{"title":"Table of 1322"}}
[
{
"title":"Table of 1322",
"id":"7"
}
]
To find a resource using its identifier, the id argument of the URL can be use (e.g. find the work that has the id 7).
Note that only one record will be returned, i.e. it won't be contained in an array, even if you don't specify hits=true.
https://dishas.obspm.fr/elastic-query?index=work&source=["id","title"]&id=7
{
"title":"Table of 1322",
"id":"7"
}
Data structure
Table edition
"edited_text" : {
"id" : "edited text id",
"edited_text_title" : "edited text title",
"date" : "edition date",
"type" : "edition type",
"online_resource" : "edition URL",
"comment" : "commentary on the edition",
"public" : true,
"secondary_source" : "title of the secondary source if one exists",
"table_type" : {
"astronomical_object" : {
"id" : "astronomical object id",
"object_name" : "astronomical object name",
"color" : "astronomical object color",
"object_definition" : "astronomical object color"
},
"id" : "table type id",
"table_type_name" : "table type name",
"astro_definition" : "table type definition",
"kibana_name" : "table type complete name"
},
"historian" : {
"kibana_name" : "intellectual author name",
"kibana_id" : "Historian + intellectual author id"
},
"page_range" : "edition page range in the secondary source",
"original_texts" : [
{ ... }, { ... }
],
"related_editions_ext" : null,
"created" : "creation date of the record",
"updated" : "update date of the record",
"table_contents" : [
{ ... }, { ... }
],
"era" : "starting date of the edited table",
"kibana_name" : "edited text complete title",
"kibana_id" : "EditedText + edited text id"
}
Table content
"table_content" : {
"argument1_number_of_steps" : "number of rows in table",
"argument2_number_of_steps" : "number of columns (in case there is two arguments",
"id" : "table content id",
"value_original" : {
"args" : {
"argument1" : [ every first argument values in table content in the original type of number ],
("argument2" : [ every second argument values in table content in the original type of number if there is one ])
},
"entry" : [ every entry values in table content in the original type of number ],
("symmetries" : [ table values that are part of a symmetry ],)
"template" : {
"table_type" : "table type id of the table content",
"readonly" : "if the table values are only to be read",
"args" : [
{
"name" : "name of the first argument",
"type" : "type of number of the argument",
"unit" : "number unit id of the argument",
"nsteps" : "number of row/column for the argument",
"ncells" : "total number of cells (fractional and non fractional part)",
"decpos" : "number of cell before the fractional part",
"subUnit" : "sub unit",
"firstMonth" : "first month of the year (for certain type of tables)"
}
],
"entries" : [
{
"name" : "name of the entries",
"type" : "type of number of the entries",
"ncells" : "total number of cells (fractional and non fractional part)",
"decpos" : "number of cell before the fractional part",
"unit" : "number of unit id of the entries"
}
]
}
},
"value_float" : { same as value original but in float },
"corrected_value_float" : { same as value float but with corrected values },
"entry_type_of_number" : "type of number name of the entries",
"entry_number_unit" : "number unit name of the entries",
"entry_significant_fractional_place" : "number of cell after the fractional part for the entries",
"entry_number_of_cell" : "total number of cell for the entries",
"argument1_name" : "name of the first argument",
"argument1_type_of_number" : "type of number name of the first argument",
"argument1_number_unit" : "number of unit id of the first argument",
"argument1_number_of_cell" : "total number of cell for the first argument",
"argument1_significant_fractional_place" : "number of cell after the fractional part for the first argument",
"argument2_name" : "name of the second argument",
"argument2_type_of_number" : "type of number name of the second argument",
"argument2_number_unit" : "number of unit id of the second argument",
"argument2_number_of_cell" : "total number of cell for the second argument",
"argument2_significant_fractional_place" : "number of cell after the fractional part for the second argument",
"comment" : "comment on the table content",
"mathematical_parameter" : "mathematical parameter complete name",
"parameter_sets" : [
{ ... }, { ... }
],
"created" : "creation date of the table content record",
"updated" : "update date of the table content",
"public" : true,
"mean_motion" : "is the table content part of a mean motion",
"kibana_name" : "table content complete title",
"kibana_id" : "TableContent + table content id"
}
Table witness
"original_text" : {
"id" : "original text id",
"text_type" : "astronomicalTable",
"original_text_title" : "original text title transliterated",
"original_text_title_original_char" : "original text title in original character",
"language" : "original text language",
"script" : "original text script",
"tpq" : "original text terminus ante quem",
"tpq" : "original text terminus post quem",
"page_min" : "minimal page in which the original text is to be found",
"page_max" : "maximal page in which the original text is to be found",
"is_folio" : is the original text in a folioed primary source,
"comment" : "comment on the original text",
"public" : true,
"created" : "creation date of the record",
"updated" : "update date of the record",
"table_type" : "table type name",
"place" : {
"location" : "latitude,longitude of the original text place of creation",
"kibana_name" : "place of creation name of the original text",
"kibana_id" : "Place + original text creation place id"
},
"primary_source" : { ... },
"work" : { ... },
"historical_actor" : {
"viaf_identifier" : "original text scribal agent VIAF identifier",
"kibana_name" : "original text scribal agent complete name",
"kibana_id" : "HistoricalActor + original text scribal agent id"
},
"edited_texts" : [
{ ... }, { ... }
],
"tpq_date" : "original text normalized terminus post quem (YYYY-01-01)",
"taq_date" : "original text normalized terminus ante quem",
"kibana_name" : "original text complete title",
"kibana_id" : "OriginalText + original text id"
}
Primary source
"primary_source" : {
"id" : "primary source id",
"prim_type" : "primary source type: ep/ms",
"digital_identifier" : "primary source URL in the catalogue of the curation library",
"prim_title" : "primary source edition title transliterated",
"prim_title_original_char" : "primary source edition title in original character",
"date" : "primary source edition date",
"library" : {
"kibana_name" : "library complete name",
"kibana_id" : "Library + library id"
},
"kibana_name" : "primary source complete name",
"default_title" : "primary source shelfmark | primary source library",
"kibana_id" : "PrimarySource + primary source id",
"original_texts" : [
{ ... }, { ... }
],
"tpq" : "primary source terminus ante quem",
"tpq" : "primary source terminus post quem",
"tpq_date" : "primary source normalized terminus post quem (YYYY-01-01)",
"taq_date" : "primary source normalized terminus ante quem",
"places" : [
{
"location" : "latitude,longitude of the primary source place of creation",
"kibana_name" : "place of creation name of the primary source",
"kibana_id" : "Place + primary source creation place id"
}, { ... }
]
}
Work
"work" : {
"id" : "work id",
"incipit" : "work incipit",
"incipit_original_char" : "work incipit in original character",
"title" : "work title",
"title_original_char" : "work title in original character",
"taq" : "work terminus ante quem",
"tpq" : "work terminus post quem",
"place" : {
"location" : "latitude,longitude of the work place of creation",
"kibana_name" : "place of creation name of the work",
"kibana_id" : "Place + work creation place id"
},
"historical_actors" : [
{
"viaf_identifier" : "work creator VIAF identifier",
"kibana_name" : "work creator complete name",
"kibana_id" : "HistoricalActor + work creator id"
}
],
"translator" : {
"viaf_identifier" : "work translator VIAF identifier",
"kibana_name" : "work translator complete name",
"kibana_id" : "HistoricalActor + work translator id"
},
"original_texts" : [
{ ... }, { ... }
],
"tpq_date" : "work normalized terminus post quem (YYYY-01-01)",
"taq_date" : "work normalized terminus ante quem",
"kibana_name" : "work complete title",
"kibana_id" : "Work + work id",
"default_title" : "work default title"
}
Parameter set
"parameter_set" : {
"id" : "parameter id",
"created" : "parameter record creation date",
"table_type" : {
"astronomical_object" : {
"id" : "astronomical object id",
"object_name" : "astronomical object name",
"color" : "astronomical object color",
"object_definition" : "astronomical object definition"
},
"id" : "table type id",
"table_type_name" : "table type name",
"astro_definition" : "table type definition",
"kibana_name" : "table type complete name"
},
"parameter_values" : [
{
"type_of_number" : "parameter value type of number",
"parameter_format" : {
"id" : "parameter value name id",
"parameter_name" : "parameter value name",
"parameter_type" : "explicit/implicit",
"parameter_unit" : "parameter value units for entry and/or arguments"
},
"kibana_name" : "parameter value complete name",
"kibana_id" : "ParameterValue + parameter value id",
"default_title" : "parameter values concatenated",
"values" : {
"original" : {
"value" : "value of the parameter in original type of number",
"arg1" : {
"from" : "minimum value for the first argument in original type of number",
"to" : "maximum value for the first argument in original type of number"
},
"arg2" : {
"from" : "minimum value for the second argument in original type of number",
"to" : "maximum value for the second argument in original type of number"
},
"arg3" : {
"from" : "minimum value for the entries in original type of number",
"to" : "maximum value for the entries in original type of number"
}
},
"float" : { same as original but values expressed in float }
}
}, { ... }
],
"table_contents" : [
{
"edited_text" : {
"kibana_id" : "EditedText + edited text id"
},
"kibana_name" : "edited text complete title",
"kibana_id" : "TableContent + table content id"
}, { ... }
],
"default_title" : "parameter set original values",
"kibana_name" : "parameter set complete name",
"kibana_id" : "ParameterSet + parameter set id"
}
Formula definition
"formula_definition" : {
"id" : "formula id",
"name" : "formula name",
"author" : {
"kibana_name" : "author complete name",
"kibana_id" : "Historian + author id"
},
"explanation" : "formula explanation",
"tip" : "formula tip",
"modern_definition" : "formula modern definition",
"bibliography" : "formula bibliography",
"parameter_explanation" : "formula parameter explanation",
"estimator_definition" : "formula estimator definition",
"arg_number" : "number of arguments in for the formula",
"table_type" : {
"astronomical_object" : {
"id" : "astronomical object id",
"object_name" : "astronomical object name",
"color" : "astronomical object color",
"object_definition" : "astronomical object definition"
},
"id" : "table type id",
"table_type_name" : "table type name",
"astro_definition" : "definition of the table type",
"kibana_name" : "table type complete name"
},
"kibana_name" : "formula complete name",
"kibana_id" : "FormulaDefinition + formula id"
}
Elasticsearch query language
You can find detailed examples of elasticsearch queries in this wiki.
Geo query
The location property in an index indicate that it is possible to perform a geo query on this field.
https://dishas.obspm.fr/elastic-query?index=primary_source&query={"bool":{"filter":{"geo_distance":{"distance":"100km","original_texts.place.location":{"lat":48.8,"lon":2.3}}}}}
All primary sources that containing at least one table that has been copied or printed within
a radius of less than 100 km from Paris (lat. 48.8 - long. 2.3)
{
"bool": {
"filter": {
"geo_distance": {
"distance": "100km",
"original_texts.place.location": {
"lat": 48.8,
"lon": 2.3
}
}
}
}
}
Query on parameter values
The parameter_values property of the parameter_set index is of a special data type, i.e. nested data type. It allows to perform nested queries that execute several filters on the same parameter value.
https://dishas.obspm.fr/elastic-query?index=parameter_set&query={"nested":{"path":"parameter_values","query":{"bool":{"must":[{"range":{"parameter_values.values.float.value":{"gte":2,"lte":3}}},{"match":{"parameter_values.parameter_format.id":"50"}}]}}}}
All parameter sets that have at least one value for the solar eccentricity (parameter format n°50)
that is between 2 and 3.
{
"nested": {
"path": "parameter_values",
"query": {
"bool": {
"must": [
{
"range": {"parameter_values.values.float.value": {"gte": 2,"lte": 3}}
},
{
"match": {"parameter_values.parameter_format.id": "50"}
}
]
}
}
}
}