DataGEMs WP3 Demo API 0.3.0¶
A collection of APIs for DataGEMs WP3
Endpoints¶
GET /¶
Read Root
Responses
Schema of the response body
GET /explore¶
Explore
Description
Endpoint to explore the API and its capabilities.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No | |
question |
query | string | No |
Responses
Schema of the response body
{
"additionalProperties": true,
"title": "Response Explore Explore Get",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
GET /health¶
Health
Responses
Schema of the response body
GET /text2geo¶
Geospatial Query
Description
Endpoint to handle geospatial queries using OverpassQLTool.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No | |
question |
query | string | No |
Responses
{
"most_relevant_wikidata": {
"place": "Zurich",
"reasoning": "The question asks for the city of Zurich, which is best represented by the entity with ID Q72. This entity is described as the capital of the canton of Zurich and is a municipality and city in Switzerland. It also has 'found_osm_json: True', which gives it priority if multiple similar entities were found. Other entities like universities or sports clubs are not relevant to the context of the question, which specifically asks for the city.",
"wiki_id": "Q72",
"wiki_properties": {
"aliases": "City of Zurich, ZH, Stadt Zürich, Zurich, Switzerland, Zürich",
"coordinate location": "47.37444444444444, 8.54111111111111",
"country": "Switzerland, Old Swiss Confederacy, Helvetic Republic, Switzerland",
"description": "capital of the canton of Zurich, Switzerland",
"found_osm_json": true,
"instance of": "municipality of Switzerland, city of Switzerland, cantonal capital of Switzerland, college town, largest city, big city",
"label": "Zurich",
"located in the administrative territorial entity": "Zürich District",
"part of": "Greater Zurich Area, Zurich metropolitan area, Canton of Zürich"
}
},
"oql": {
"OQL": "area[\"ISO3166-1\"=\"CH\"]->.searchArea;(nwr[\"wikidata\"=\"Q72\"];);",
"reasoning": "Generated Overpass QL query using Wikidata ID Q72 and country ISO alpha-2 code CH."
},
"place": "zurich",
"results": {
"bounds": {
"maxlat": 47.4346662,
"maxlon": 8.6254413,
"minlat": 47.3202187,
"minlon": 8.4480061
},
"center": [
47.4,
8.5
],
"geojson_data": {
"features": [],
"type": "FeatureCollection"
},
"points": [
{
"lat": "47.4",
"lon": "8.5"
}
]
}
}
Schema of the response body
{
"example": {
"most_relevant_wikidata": {
"place": "Zurich",
"reasoning": "The question asks for the city of Zurich, which is best represented by the entity with ID Q72. This entity is described as the capital of the canton of Zurich and is a municipality and city in Switzerland. It also has 'found_osm_json: True', which gives it priority if multiple similar entities were found. Other entities like universities or sports clubs are not relevant to the context of the question, which specifically asks for the city.",
"wiki_id": "Q72",
"wiki_properties": {
"aliases": "City of Zurich, ZH, Stadt Zürich, Zurich, Switzerland, Zürich",
"coordinate location": "47.37444444444444, 8.54111111111111",
"country": "Switzerland, Old Swiss Confederacy, Helvetic Republic, Switzerland",
"description": "capital of the canton of Zurich, Switzerland",
"found_osm_json": true,
"instance of": "municipality of Switzerland, city of Switzerland, cantonal capital of Switzerland, college town, largest city, big city",
"label": "Zurich",
"located in the administrative territorial entity": "Zürich District",
"part of": "Greater Zurich Area, Zurich metropolitan area, Canton of Zürich"
}
},
"oql": {
"OQL": "area[\"ISO3166-1\"=\"CH\"]->.searchArea;(nwr[\"wikidata\"=\"Q72\"];);",
"reasoning": "Generated Overpass QL query using Wikidata ID Q72 and country ISO alpha-2 code CH."
},
"place": "zurich",
"results": {
"bounds": {
"maxlat": 47.4346662,
"maxlon": 8.6254413,
"minlat": 47.3202187,
"minlon": 8.4480061
},
"center": [
47.4,
8.5
],
"geojson_data": {
"features": [],
"type": "FeatureCollection"
},
"points": [
{
"lat": "47.4",
"lon": "8.5"
}
]
}
},
"properties": {
"most_relevant_wikidata": {
"$ref": "#/components/schemas/MostRelevantWikidata",
"description": "The most relevant Wikidata entity related to the query."
},
"oql": {
"$ref": "#/components/schemas/OQLResponse",
"description": "The OverpassQL query generated from the geospatial question."
},
"place": {
"description": "The place identified in the geospatial query.",
"title": "Place",
"type": "string"
},
"results": {
"$ref": "#/components/schemas/GeospatialResults",
"description": "The results of the OverpassQL query includes points, bounding box, multipolygons and centroid."
}
},
"required": [
"place",
"most_relevant_wikidata",
"oql",
"results"
],
"title": "GeospatialResponse",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
POST /text2sql¶
Text2Sql Query
Description
Endpoint to handle text to SQL queries.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No |
Request body
{
"parameters": {
"db_database": "database_name",
"db_host": "the_db_host_ip",
"db_pass": "db_password",
"db_port": 5432,
"db_schema": "database_schema",
"db_username": "db_username"
},
"question": "What are the average mean temperatures in the coordinates (latitude, longitude) in year 2020?"
}
Schema of the request body
{
"properties": {
"parameters": {
"$ref": "#/components/schemas/SQLQueryParameters",
"description": "The parameters for the SQL query, including results.",
"example": {
"db_info": {
"db_database": "database_name",
"db_host": "the_db_host_ip",
"db_pass": "db_password",
"db_port": 5432,
"db_schema": "database_schema",
"db_username": "db_username"
},
"results": {
"points": [
[
47.4,
8.4
],
[
47.4,
8.5
]
]
}
}
},
"question": {
"description": "The text question to be converted to SQL.",
"example": "What are the average mean temperatures in the coordinates (latitude, longitude) in year 2020?",
"title": "Question",
"type": "string"
}
},
"required": [
"question",
"parameters"
],
"title": "Text2SQLQuery",
"type": "object"
}
Responses
{
"input_params": [
{
"latitude": 47.4,
"longitude": 8.4
},
{
"latitude": 47.4,
"longitude": 8.5
}
],
"message": "Successfully generated SQL query on the first attempt.",
"model_name": "qwen-qwq",
"output_params": {
"coordinates": [
"latitude",
"longitude"
]
},
"params": {
"points": [
[
47.4,
8.4
],
[
47.4,
8.5
]
]
},
"question": "What are the average mean temperatures in the coordinates (lat, lon) in year 2020?",
"reasoning": "The SQL template calculates the average temperature in Celsius for the specified coordinates in 2020. The coordinates are rounded to 1 decimal place for matching. The meteo_tmean table is used for temperature data (tmean in Kelvin), converted to Celsius by subtracting 273.15. The WHERE clause filters records to the year 2020 and matches the rounded coordinates from the input parameters.",
"sql_pattern": "SELECT ROUND(CAST(latitude AS NUMERIC), 1) AS rounded_latitude, ROUND(CAST(longitude AS NUMERIC), 1) AS rounded_longitude, AVG(tmean - 273.15) AS avg_temp_celsius FROM era5_land2.meteo_tmean WHERE EXTRACT(YEAR FROM time) = 2020 AND (ROUND(CAST(latitude AS NUMERIC), 1), ROUND(CAST(longitude AS NUMERIC), 1)) IN {coordinates} GROUP BY rounded_latitude, rounded_longitude",
"sql_query": "SELECT ROUND(CAST(latitude AS NUMERIC), 1) AS rounded_latitude, ROUND(CAST(longitude AS NUMERIC), 1) AS rounded_longitude, AVG(tmean - 273.15) AS avg_temp_celsius FROM era5_land2.meteo_tmean WHERE EXTRACT(YEAR FROM time) = 2020 AND (ROUND(CAST(latitude AS NUMERIC), 1), ROUND(CAST(longitude AS NUMERIC), 1)) IN ((47.4, 8.4), (47.4, 8.5)) GROUP BY rounded_latitude, rounded_longitude",
"sql_results": {
"data": [
{
"avg_temp_celsius": 10.613293907290531,
"rounded_latitude": "47.4",
"rounded_longitude": "8.4"
},
{
"avg_temp_celsius": 10.440176525011696,
"rounded_latitude": "47.4",
"rounded_longitude": "8.5"
}
],
"status": "success"
},
"status": "success"
}
Schema of the response body
{
"example": {
"input_params": [
{
"latitude": 47.4,
"longitude": 8.4
},
{
"latitude": 47.4,
"longitude": 8.5
}
],
"message": "Successfully generated SQL query on the first attempt.",
"model_name": "qwen-qwq",
"output_params": {
"coordinates": [
"latitude",
"longitude"
]
},
"params": {
"points": [
[
47.4,
8.4
],
[
47.4,
8.5
]
]
},
"question": "What are the average mean temperatures in the coordinates (lat, lon) in year 2020?",
"reasoning": "The SQL template calculates the average temperature in Celsius for the specified coordinates in 2020. The coordinates are rounded to 1 decimal place for matching. The meteo_tmean table is used for temperature data (tmean in Kelvin), converted to Celsius by subtracting 273.15. The WHERE clause filters records to the year 2020 and matches the rounded coordinates from the input parameters.",
"sql_pattern": "SELECT ROUND(CAST(latitude AS NUMERIC), 1) AS rounded_latitude, ROUND(CAST(longitude AS NUMERIC), 1) AS rounded_longitude, AVG(tmean - 273.15) AS avg_temp_celsius FROM era5_land2.meteo_tmean WHERE EXTRACT(YEAR FROM time) = 2020 AND (ROUND(CAST(latitude AS NUMERIC), 1), ROUND(CAST(longitude AS NUMERIC), 1)) IN {coordinates} GROUP BY rounded_latitude, rounded_longitude",
"sql_query": "SELECT ROUND(CAST(latitude AS NUMERIC), 1) AS rounded_latitude, ROUND(CAST(longitude AS NUMERIC), 1) AS rounded_longitude, AVG(tmean - 273.15) AS avg_temp_celsius FROM era5_land2.meteo_tmean WHERE EXTRACT(YEAR FROM time) = 2020 AND (ROUND(CAST(latitude AS NUMERIC), 1), ROUND(CAST(longitude AS NUMERIC), 1)) IN ((47.4, 8.4), (47.4, 8.5)) GROUP BY rounded_latitude, rounded_longitude",
"sql_results": {
"data": [
{
"avg_temp_celsius": 10.613293907290531,
"rounded_latitude": "47.4",
"rounded_longitude": "8.4"
},
{
"avg_temp_celsius": 10.440176525011696,
"rounded_latitude": "47.4",
"rounded_longitude": "8.5"
}
],
"status": "success"
},
"status": "success"
},
"properties": {
"input_params": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/InputParam"
},
"type": "array"
},
{
"type": "null"
}
],
"description": "Input parameters with coordinates.",
"title": "Input Params"
},
"message": {
"description": "Message describing the operation result.",
"title": "Message",
"type": "string"
},
"model_name": {
"description": "The model name used for SQL generation.",
"title": "Model Name",
"type": "string"
},
"output_params": {
"anyOf": [
{
"$ref": "#/components/schemas/OutputParams"
},
{
"type": "null"
}
],
"description": "Output parameter definitions."
},
"params": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"description": "Parameters used in the query.",
"title": "Params"
},
"question": {
"description": "The original question that was converted to SQL.",
"title": "Question",
"type": "string"
},
"reasoning": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Reasoning behind the SQL query generation.",
"title": "Reasoning"
},
"sql_pattern": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The SQL pattern/template generated.",
"title": "Sql Pattern"
},
"sql_query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The final SQL query with parameters filled in.",
"title": "Sql Query"
},
"sql_results": {
"anyOf": [
{
"$ref": "#/components/schemas/SQLResults"
},
{
"type": "null"
}
],
"description": "Results from executing the SQL query."
},
"status": {
"description": "Status of the operation.",
"title": "Status",
"type": "string"
}
},
"required": [
"status",
"message",
"question",
"model_name"
],
"title": "Text2SQLResponse",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
},
{
"Key": "parameters.results.points",
"Value": [
"Field required"
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
POST /textQuestionAnswer¶
Text Question Answer Query
Description
Endpoint to summarize RAG content for a question.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
OAuth2PasswordBearer |
header | string | N/A | No |
Request body
{
"question": "What is the chief town of the island of COPRAJA?",
"rag_output": {
"query_time": null,
"results": [
{
"content": "string",
"dataset_id": "string",
"object_id": "string",
"similarity": 10.12
}
]
}
}
Schema of the request body
{
"properties": {
"question": {
"description": "The user question that should be answered from the provided RAG chunks.",
"example": "What is the chief town of the island of COPRAJA?",
"title": "Question",
"type": "string"
},
"rag_output": {
"$ref": "#/components/schemas/RagOutput",
"description": "Raw RAG output containing retrieved chunks and metadata.",
"example": {
"query_time": 3263.56,
"results": [
{
"content": "COPRAJA, an island in the Mediterranean Sea... The chief town is Tratozzio.",
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"object_id": "kp-eb0707-031203-1328-v2.xml",
"similarity": 1.0
}
]
}
}
},
"required": [
"question",
"rag_output"
],
"title": "TextQuestionAnswerQuery",
"type": "object"
}
Responses
{
"answerable": true,
"reason_code": "ANSWERED",
"summary": "Based on the provided context, the chief town of COPRAJA is Tratozzio.",
"used_chunks": [
{
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"object_id": "kp-eb0707-031203-1328-v2.xml",
"similarity": 1.0
}
]
}
Schema of the response body
{
"example": {
"answerable": true,
"reason_code": "ANSWERED",
"summary": "Based on the provided context, the chief town of COPRAJA is Tratozzio.",
"used_chunks": [
{
"dataset_id": "d84d1a2e-127d-4393-91d0-afb7e4fd9c68",
"object_id": "kp-eb0707-031203-1328-v2.xml",
"similarity": 1.0
}
]
},
"properties": {
"answerable": {
"description": "Whether the model determined the context is sufficient to answer.",
"title": "Answerable",
"type": "boolean"
},
"reason_code": {
"description": "Structured reason code from summarization decision.",
"title": "Reason Code",
"type": "string"
},
"summary": {
"description": "Summary answer generated from RAG chunks.",
"title": "Summary",
"type": "string"
},
"used_chunks": {
"description": "Sources used by the summarization step.",
"items": {
"$ref": "#/components/schemas/SummarySource"
},
"title": "Used Chunks",
"type": "array"
}
},
"required": [
"answerable",
"reason_code",
"summary",
"used_chunks"
],
"title": "TextQuestionAnswerResponse",
"type": "object"
}
{
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
},
{
"Key": "rag_output.results",
"Value": [
"Field required"
]
}
]
}
Schema of the response body
{
"example": {
"code": 102,
"error": "validation error",
"message": [
{
"Key": "question",
"Value": [
"Field required"
]
}
]
},
"properties": {
"code": {
"title": "Code",
"type": "integer"
},
"error": {
"title": "Error",
"type": "string"
},
"message": {
"items": {
"$ref": "#/components/schemas/ValidationErrorDetail"
},
"title": "Message",
"type": "array"
}
},
"required": [
"code",
"error",
"message"
],
"title": "ValidationErrorResponse",
"type": "object"
}
Schemas¶
Bounds¶
| Name | Type | Description |
|---|---|---|
maxlat |
number | Maximum latitude. |
maxlon |
number | Maximum longitude. |
minlat |
number | Minimum latitude. |
minlon |
number | Minimum longitude. |
GeospatialResponse¶
| Name | Type | Description |
|---|---|---|
most_relevant_wikidata |
MostRelevantWikidata | The most relevant Wikidata entity related to the query. |
oql |
OQLResponse | The OverpassQL query generated from the geospatial question. |
place |
string | The place identified in the geospatial query. |
results |
GeospatialResults | The results of the OverpassQL query includes points, bounding box, multipolygons and centroid. |
GeospatialResults¶
| Name | Type | Description |
|---|---|---|
bounds |
Bounds | Bounding box of the results. |
center |
Array<number> | Center coordinates as [lat, lon]. |
geojson_data |
GeoJSON feature collection data. | |
points |
Array<Point> | List of points with coordinates. |
HTTPValidationError¶
| Name | Type | Description |
|---|---|---|
detail |
Array<ValidationError> |
InputParam¶
MostRelevantWikidata¶
| Name | Type | Description |
|---|---|---|
place |
string | The place name. |
reasoning |
string | Reasoning for selecting this entity. |
wiki_id |
string | The Wikidata ID. |
wiki_properties |
WikiProperties | Properties of the Wikidata entity. |
OQLResponse¶
| Name | Type | Description |
|---|---|---|
OQL |
string | The OverpassQL query string. |
reasoning |
string | Reasoning for the generated OQL query. |
OutputParams¶
| Name | Type | Description |
|---|---|---|
coordinates |
Array<string> | List of coordinate parameter names. |
Point¶
| Name | Type | Description |
|---|---|---|
lat |
string | Latitude as string. |
lon |
string | Longitude as string. |
RagOutput¶
| Name | Type | Description |
|---|---|---|
query_time |
RAG query execution time in milliseconds. | |
results |
Array<RagResultItem> | Retrieved chunks from the RAG system. |
RagResultItem¶
| Name | Type | Description |
|---|---|---|
content |
string | Retrieved content chunk from the RAG system. |
dataset_id |
string | Dataset identifier for the source. |
object_id |
string | Object identifier for the source chunk. |
similarity |
number | Similarity score returned by the RAG system. |
ResultsModel¶
| Name | Type | Description |
|---|---|---|
points |
Array<Array<number>> | List of points with coordinates. |
SQLQueryParameters¶
| Name | Type | Description |
|---|---|---|
db_info |
Database connection information. | |
results |
The results containing points for SQL query. |
SQLResults¶
| Name | Type | Description |
|---|---|---|
data |
Array<> | Results data from the SQL query. |
status |
string | Status of the SQL query execution. |
SummarySource¶
| Name | Type | Description |
|---|---|---|
dataset_id |
string | Dataset identifier for the source. |
object_id |
string | Object identifier for the source chunk. |
similarity |
number | Similarity score for this source. |
Text2SQLQuery¶
| Name | Type | Description |
|---|---|---|
parameters |
SQLQueryParameters | The parameters for the SQL query, including results. |
question |
string | The text question to be converted to SQL. |
Text2SQLResponse¶
| Name | Type | Description |
|---|---|---|
input_params |
Input parameters with coordinates. | |
message |
string | Message describing the operation result. |
model_name |
string | The model name used for SQL generation. |
output_params |
Output parameter definitions. | |
params |
Parameters used in the query. | |
question |
string | The original question that was converted to SQL. |
reasoning |
Reasoning behind the SQL query generation. | |
sql_pattern |
The SQL pattern/template generated. | |
sql_query |
The final SQL query with parameters filled in. | |
sql_results |
Results from executing the SQL query. | |
status |
string | Status of the operation. |
TextQuestionAnswerQuery¶
| Name | Type | Description |
|---|---|---|
question |
string | The user question that should be answered from the provided RAG chunks. |
rag_output |
RagOutput | Raw RAG output containing retrieved chunks and metadata. |
TextQuestionAnswerResponse¶
| Name | Type | Description |
|---|---|---|
answerable |
boolean | Whether the model determined the context is sufficient to answer. |
reason_code |
string | Structured reason code from summarization decision. |
summary |
string | Summary answer generated from RAG chunks. |
used_chunks |
Array<SummarySource> | Sources used by the summarization step. |
ValidationError¶
| Name | Type | Description |
|---|---|---|
ctx |
||
input |
||
loc |
Array<> | |
msg |
string | |
type |
string |
ValidationErrorDetail¶
| Name | Type | Description |
|---|---|---|
Key |
string | |
Value |
Array<string> |
ValidationErrorResponse¶
| Name | Type | Description |
|---|---|---|
code |
integer | |
error |
string | |
message |
Array<ValidationErrorDetail> |
WikiProperties¶
| Name | Type | Description |
|---|---|---|
aliases |
Aliases for the Wikidata entity. | |
coordinate location |
Coordinate location. | |
country |
Country information. | |
description |
The description of the Wikidata entity. | |
found_osm_json |
boolean | Whether OSM JSON was found. |
instance of |
Instance types of the entity. | |
label |
The label of the Wikidata entity. | |
located in the administrative territorial entity |
Administrative location. | |
part of |
What the entity is part of. |
Security schemes¶
| Name | Type | Scheme | Description |
|---|---|---|---|
| OAuth2PasswordBearer | oauth2 |