Gobierto Data
Gobierto Data API provides a way to use the data module in a programmatic way by exposition the following resources:
And also provides a way to run plain SQL queries on any of the available tables.
Lear more about this module in [Datos]
Run a SQL query
GET /api/v1/data/data{.json|.csv|.xlsx}
Returns the result of a query in the specified format. By default the csv format uses comma as column separator. Only tables belonging to active datasets can be accessed by the query. To access draft tables a valid preview_token must be included in the request params. If the response is requested in JSON format the data is limited to 50 first rows by default.
Parameters:
sql: An sql query to be sent to the module database connection.csv_separator: A string to be used as separator of columns in output. The default column separator is,. There are some keys for special characters:comma: Equivalent to use%2Cor,.semicolon: Equivalent to use%3Bin the query. The use of;produces a wrong csv.colon: Equivalent to use%3Aor:.
data_preview: Default:true. This parameter is only taken into account if the requested format is JSON. Whentrueor not provided the"data"values of the response is limited to the 50 first rows of the query used.
Example request: /api/v1/data/data.csv?sql=SELECT * FROM wadus&csv_separator=semicolon
Response: JSON (default), CSV, XLSX
JSON response schema:
{
"data": [ 50 first rows of query result unless data_preview=false in the request ],
"meta": {
"duration": ···,
"rows": ···,
"status": ···
}
}
Datasets
List datasets
GET /api/v1/data/datasets{.json|.csv|.xlsx}
List of all datasets in specified format
Parameters:
filter: The usage of the filter is as described belowcsv_separator: A string to be used as separator of columns in output. The default column separator is,. There are some keys for special characters:comma: Equivalent to use%2Cor,.semicolon: Equivalent to use%3Bin the query. The use of;produces a wrong csv.colon: Equivalent to use%3Aor:.
Example request: /api/v1/data/datasets
Response: JSON (default), CSV, XLSX
JSON response schema:
{
"data": [
{
"id": ···,
"type": "gobierto_data-datasets",
"attributes": {
"name": ···,
"slug": ···,
"table_name": ···,
"data_updated_at": ···,
"columns": {
"column_name": "data_type"[, ···]
}
"links": {
"data": "/api/v1/data/datasets/···",
"metadata": "/api/v1/data/datasets/···/meta"
},
[ variable list of custom fields values ]
}
}[, ···]
],
"links": {
"datasets_meta": "/api/v1/data/datasets/meta",
"queries": "/api/v1/data/queries",
"visualizations": "/api/v1/data/visualizations",
"self": "/api/v1/data/datasets"
}
}
Get metadata from datasets
GET /api/v1/data/datasets/meta
Information about custom fields defined for datasets
Parameters:
stats: When true additional queries and calculations are performed for custom field values. The results are included in ametaattribute. Depending on field type the information can include maximum and minimum, distributions or histograms.
Example request: /api/v1/data/datasets/meta
Response: JSON
Get data from dataset
GET /api/v1/data/datasets/DATASET-SLUG{.json|.csv|.xlsx}
The content of the given dataset in the specified format (see if/how DCAT points to datasets). If the response is requested in JSON format the content is limited to 50 first rows by default.
Parameters:
csv_separator: A string to be used as separator of columns in output. The default column separator is,. There are some keys for special characters:comma: Equivalent to use%2Cor,.semicolon: Equivalent to use%3Bin the query. The use of;produces a wrong csv.colon: Equivalent to use%3Aor:.
data_preview: Default:true. This parameter is only taken into account if the requested format is JSON. Whentrueor not provided the"data"values of the response is limited to the 50 first rows of the query used.
Example request: /api/v1/data/datasets/presupuestos
Response: JSON (default), CSV, XLSX
JSON response schema:
{
"data": [ 50 first rows of table unless data_preview=false in the request ],
"meta": {
"duration": ···,
"rows": ···,
"status": ···
},
"links": {
"index": "/api/v1/data/datasets",
"datasets_meta": "/api/v1/data/datasets/meta",
"queries": "/api/v1/data/queries?dataset_id=DATASET-ID",
"visualizations": "/api/v1/data/visualizations?dataset_id=DATASET-ID",
"metadata": "/api/v1/data/datasets/DATASET-SLUG/meta",
"self": "/api/v1/data/datasets/DATASET-SLUG"
}
}
Get metadata from dataset
GET /api/v1/data/datasets/DATASET-SLUG/meta
Metadata, data summary and data preview of the given dataset. If the dataset has attachments, their IDs appear in the relationships section and their complete metadata is included in the included section.
Example request: /api/v1/data/datasets/presupuestos/meta
Response: JSON
Response schema:
{
"data": {
"id": ···,
"type": "gobierto_data-datasets",
"attributes": {
"name": ···,
"slug": ···,
"table_name": ···,
"data_updated_at": ···,
"columns": {
"column_name": "data_type"[, ···]
},
"data_summary": {
"number_of_rows": ···
},
"formats": {
"json": "/api/v1/data/datasets/DATASET-SLUG/download.json",
"csv": "/api/v1/data/datasets/DATASET-SLUG/download.csv",
"xlsx": "/api/v1/data/datasets/DATASET-SLUG/download.xlsx"
},
"data_preview": [first 50 rows],
"description": "",
"frequency": [],
"category": [],
[ variable list of custom fields values ]
},
"relationships": {
"queries": {
"data": [
{
"id": ···,
"type": "gobierto_data-queries"
}[, ···]
]
},
"visualizations": {
"data": [
{
"id": ···,
"type": "gobierto_data-visualizations"
}[, ···]
]
},
"attachments": {
"data": [
{
"id": ···,
"type": "gobierto_attachments-attachments"
}[, ···]
]
}
}
},
"included": [
{
"id": ···,
"type": "gobierto_attachments-attachments",
"attributes": {
"name": ···,
"description": ···,
"file_name": ···,
"file_digest": ···,
"url": ···,
"human_readable_url": ···,
"file_size": ···,
"current_version": ···,
"created_at": ···,
"updated_at": ···
}
}[, ···]
],
"links": {
"index": "/api/v1/data/datasets",
"datasets_meta": "/api/v1/data/datasets/meta",
"queries": "/api/v1/data/queries?filter[dataset_id]=DATASET-ID",
"visualizations": "/api/v1/data/visualizations?filter[dataset_id]=DATASET-ID",
"new": "/api/v1/data/visualizations/new",
"data": "/api/v1/data/datasets/DATASET-SLUG",
"stats": "/api/v1/data/datasets/DATASET-SLUG/stats",
"favorites": "/api/v1/data/datasets/DATASET-SLUG/favorites",
"self": "/api/v1/data/datasets/DATASET-SLUG/meta"
}
}
Get statistics from dataset
GET /api/v1/data/datasets/DATASET-SLUG/stats
Statistics of each column of dataset table. The statistics, depending on the column type may include distribution, histogram, quartiles or averages.
Example request: /api/v1/data/datasets/presupuestos/stats
Response: JSON
Response schema:
{
"data": {
"id": ···,
"type": "gobierto_data-datasets",
"attributes": {
"name": ···,
"slug": ···,
"table_name": ···,
"data_updated_at": ···,
"columns_stats": {
"text_column": {
"type": "text",
"stats": {
"not_null_count": ···,
"distinct_count": ···
}
},
"datetime_column": {
"type": "datetime",
"stats": {
"not_null_count": ···,
"distinct_count": ···,
"distribution": [
{
"value": ···,
"count": ···
}[, ...]
],
"quartiles": {
"q0": ···,
"q1": ···,
"q2": ···,
"q3": ···,
"q4": ···
},
"min": ···,
"first_quartile": ···,
"median": ···,
"third_quartile": ···,
"max": ···,
"histogram": [
{
"start": ···,
"end": ···,
"bucket": 1,
"count": ···
}[, ···]
]
}
},
"text_column": {
"type": "text",
"stats": {
"not_null_count": ···,
"distinct_count": ···,
"distribution": [
{
"value": ···,
"count": ···
}[, ···]
]
}
},
"numeric_type": {
"type": "decimal",
"stats": {
"not_null_count": ···,
"distinct_count": ···,
"distribution": [
{
"value": ···,
"count": ···
}[, ...]
],
"quartiles": {
"q0": ···,
"q1": ···,
"q2": ···,
"q3": ···,
"q4": ···
},
"min": ···,
"first_quartile": ···,
"median": ···,
"average": ···,
"third_quartile": ···,
"max": ···,
"histogram": [
{
"start": ···,
"end": ···,
"bucket": 1,
"count": ···
}[, ...]
]
}
}
}
}
},
"links": {
"index": "/api/v1/data/datasets",
"datasets_meta": "/api/v1/data/datasets/meta",
"queries": "/api/v1/data/queries?dataset_id=DATASET-ID",
"visualizations": "/api/v1/data/visualizations?dataset_id=DATASET-ID",
"new": "/api/v1/data/visualizations/new",
"data": "/api/v1/data/datasets/DATASET-SLUG",
"metadata": "/api/v1/data/datasets/DATASET-SLUG/meta",
"favorites": "/api/v1/data/datasets/DATASET-SLUG/favorites",
"self": "/api/v1/data/datasets/DATASET-SLUG/stats"
}
}
Download dataset
GET /api/v1/data/datasets/DATASET-SLUG/download{.json|.csv|.xlsx}
Content of dataset in specified format. The name of file includes the dataset slug in its name.
Example request: /api/v1/data/datasets/presupuestos/download.json
Response: JSON, CSV, XLSX
Prepare to create a new dataset
GET /api/v1/data/datasets/new
Attributes to create a new dataset. The JSON returned by this request can be used (with valid values for attributes) in the body of the next request.
This action is allowed only to authenticated admins.
Example request: /api/v1/data/datasets/new
Response: JSON
Response schema:
{
"data": {
"type": "gobierto_data-dataset_forms",
"attributes": {
"name": null,
"name_translations": {
"ca": null,
"es": null
},
"table_name": null,
"data_updated_at": null,
"slug": null,
"data_path": null,
"local_data": false,
"csv_separator": ",",
"schema": {},
"append": false
}
},
"links": {
"index": "/api/v1/data/datasets",
"datasets_meta": "/api/v1/data/datasets/meta",
"queries": "/api/v1/data/queries",
"visualizations": "/api/v1/data/visualizations",
"self": "/api/v1/data/visualizations/new"
}
}
Create a new dataset
POST /api/v1/data/datasets
Request to create a new dataset.
This action is allowed only to authenticated admins.
There are two ways to send the data to create a new dataset:
JSON body
In this way the JSON provided by the new action can be reused to send the data required to create a dataset. The following attributes are required to both create the dataset and load data from a csv into the dataset table:
nameand/orname_translations: The name of the dataset.nameis a string and internally is assigned as the translated name in the site default locale.name_translationsis an object with available locales as keys and translations of name for each locale as values. If bothname_translationsandnameare sent in the request thename_translationstakes priority overnametable_name: string with a valid name of the table.slug: string optional, if not provided it's generated from name
data_pathandlocal_data:local_datasets if the CSV data to be load in the dataset table can be accessed at the local filesystem or by a URL.data_pathis a string representing a path in the filesystem iflocal_datais true and a URL iflocal_datais false. If not provided, by defaultlocal_datais set as falsecsv_separator: String containing the separator of columns in the CSV file. If not provided by default is set as ","visibility_level: String that defines the visiblity level of the dataset. Valid values are active and draft.schema: Default: {}. JSON containing de schema of the CSV. See documentation of schema. If not provided or equals {} the schema is generated automatically considering all columns as stringsappend: Default: false. If the table already exists in the database the data from the csv is appended to it. Note that theschemaoption must be compatible with the table schema to avoid errors. If not provided, by default is set to false
Example request: /api/v1/data/datasets with body:
{
"data": {
"type": "gobierto_data-dataset_forms",
"attributes": {
"name": "New dataset",
"table_name": "new_dataset_records",
"data_path": "/home/ubuntu/2008_10k.csv",
"local_data": true,
"csv_separator": ",",
"schema": {}
}
}
}
Response: JSON
The response includes the schema used to load the data. If no schema were provided all the columns will be considered as string
Response schema:
{
"data": {
"id": ···,
"type": "gobierto_data-dataset_forms",
"attributes": {
"name": "New dataset",
"name_translations": {
"en": "New dataset",
"es": null
},
"table_name": "new_dataset_records",
"data_updated_at": ···,
"slug": "new-dataset",
"data_path": "/home/ubuntu/2008_10k.csv",
"local_data": true,
"csv_separator": ",",
"schema": {
"column_name": {
"original_name": "Column Name",
"type": "text"
}[, ···]
},
"append": false
}
},
"links": {
"index": "/api/v1/data/datasets",
"datasets_meta": "/api/v1/data/datasets/meta",
"queries": "/api/v1/data/queries?filter%5Bdataset_id%5D=116",
"visualizations": "/api/v1/data/visualizations?filter%5Bdataset_id%5D=···",
"new": "/api/v1/data/visualizations/new",
"data": "/api/v1/data/datasets/new-dataset",
"favorites": "/api/v1/data/datasets/new-dataset/favorites",
"self": "/api/v1/data/datasets/new-dataset/meta"
}
}
form-data body
This method allows us to upload a file with the csv and optionally other file with the schema JSON. The same attributes used in the previous method except data_path and local_data can be sent in the form-data nested under dataset, so the expected keys can be:
dataset[name]and/ordataset[name_translations]dataset[table_name]dataset[slug]dataset[csv_separator]dataset[visibility_level]: active or draftdataset[schema]: The value is a string that can be parsed as JSON. If a schema file is uploaded this option is ignored.dataset[append]
This method also accepts the following params to upload files:
dataset[data_file]: A field of type file with the csv containing the data to be loaddataset[schema_file]: A field of type file with the json containing the schema of the CSV
Example request using CURL
curl --location --request POST '···/api/v1/data/datasets' \
--header 'Content-Type: multipart/form-data' \
--header 'Authorization: Bearer ··· \
--form 'dataset[data_file]=@/home/ubuntu/2008_10k.csv' \
--form 'dataset[name]=New dataset' \
--form 'dataset[visibility_level]=active' \
--form 'dataset[table_name]=new_dataset_records' \
--form 'dataset[csv_separator]=\,'
Response: JSON
The response is similar to the other request:
{
"data": {
"id": ···,
"type": "gobierto_data-dataset_forms",
"attributes": {
"name": "New dataset",
"name_translations": {
"en": "New dataset",
"es": null
},
"table_name": "new_datasets_records",
"data_updated_at": ···,
"slug": "new-dataset",
"data_path": null,
"local_data": false,
"csv_separator": ",",
"schema": {
"colum_name": {
"original_name": "Column Name",
"type": "text"
}[, ···]
},
"append": false
}
},
"links": {
"index": "/api/v1/data/datasets",
"datasets_meta": "/api/v1/data/datasets/meta",
"queries": "/api/v1/data/queries?filter%5Bdataset_id%5D=···",
"visualizations": "/api/v1/data/visualizations?filter%5Bdataset_id%5D=···",
"new": "/api/v1/data/visualizations/new",
"data": "/api/v1/data/datasets/new-dataset",
"favorites": "/api/v1/data/datasets/new-dataset/favorites",
"self": "/api/v1/data/datasets/new-dataset/meta"
}
}
Update a dataset
PUT /api/v1/data/datasets/DATASET-SLUG
Request to update an existing dataset.
This action is allowed only to authenticated admins.
As in the create action there are two ways to send the data to update a dataset, with the same parameters. The append=true should be used to append data from csv. The attributes like name, table_name, slug, etc. can be ignored and remain unchanged after the update
JSON body
Example request: /api/v1/data/datasets/new-dataset with body:
{
"data": {
"type": "gobierto_data-dataset_forms",
"attributes": {
"data_path": "/home/ubuntu/2008_mini.csv",
"local_data": true,
"csv_separator": ",",
"append": true
}
}
}
Response: JSON
The response includes the schema used to load the data. If no schema were provided all the columns will be considered as string
Response schema:
{
"data": {
"id": ···,
"type": "gobierto_data-dataset_forms",
"attributes": {
"name": "New dataset",
"name_translations": {
"en": "New dataset",
"es": null
},
"table_name": "new_dataset_records",
"data_updated_at": ···,
"slug": "new-dataset",
"data_path": "/home/ubuntu/2008_mini.csv",
"local_data": true,
"csv_separator": ",",
"schema": {
"column_name": {
"original_name": "Column Name",
"type": "text"
}[, ···]
},
"append": true
}
},
"links": {
"index": "/api/v1/data/datasets",
"datasets_meta": "/api/v1/data/datasets/meta",
"queries": "/api/v1/data/queries?filter%5Bdataset_id%5D=116",
"visualizations": "/api/v1/data/visualizations?filter%5Bdataset_id%5D=···",
"new": "/api/v1/data/visualizations/new",
"data": "/api/v1/data/datasets/new-dataset",
"favorites": "/api/v1/data/datasets/new-dataset/favorites",
"self": "/api/v1/data/datasets/new-dataset/meta"
}
}
form-data body
Example request using CURL
curl --location --request PUT '···/api/v1/data/datasets/new-dataset' \
--header 'Authorization: Bearer ···' \
--header 'Content-Type: multipart/form-data; boundary=--------------------------889090071710396808775443' \
--form 'dataset[data_file]=@/home/ubuntu/2008_mini.csv' \
--form 'dataset[csv_separator]=,' \
--form 'dataset[append]=true'
Response: JSON
The response is similar to the other request:
{
"data": {
"id": ···,
"type": "gobierto_data-dataset_forms",
"attributes": {
"name": "New dataset",
"name_translations": {
"en": "New dataset",
"es": null
},
"table_name": "new_datasets_records",
"data_updated_at": ···,
"slug": "new-dataset",
"data_path": null,
"local_data": false,
"csv_separator": ",",
"schema": {
"colum_name": {
"original_name": "Column Name",
"type": "text"
}[, ···]
},
"append": false
}
},
"links": {
"index": "/api/v1/data/datasets",
"datasets_meta": "/api/v1/data/datasets/meta",
"queries": "/api/v1/data/queries?filter%5Bdataset_id%5D=···",
"visualizations": "/api/v1/data/visualizations?filter%5Bdataset_id%5D=···",
"new": "/api/v1/data/visualizations/new",
"data": "/api/v1/data/datasets/new-dataset",
"favorites": "/api/v1/data/datasets/new-dataset/favorites",
"self": "/api/v1/data/datasets/new-dataset/meta"
}
}
Delete a dataset
DELETE /api/v1/data/datasets/DATASET-SLUG
Request to delete an existing dataset.
This action is allowed only to authenticated admins.
Response:
- Return 204 No content if Success
- Return 404 Not found if the dataset don't exist
Queries
List queries
GET /api/v1/data/queries{.json|.csv|.xlsx}
List of all public queries of the site in specified format.
filter: The results can be filtered by:dataset_id: id of the dataset the queries belongs to. Syntax:filter[dataset_id]=DATASET-ID.user_id: id of the user the queries belongs to. Syntax:filter[user_id]=USER-ID. If the request is authenticated with token and the token belongs to the user withUSER-ID, all queries are listed, including closed ones.
csv_separator: A string to be used as separator of columns in output. The default column separator is,. There are some keys for special characters:comma: Equivalent to use%2Cor,.semicolon: Equivalent to use%3Bin the query. The use of;produces a wrong csv.colon: Equivalent to use%3Aor:.
Example request: /api/v1/data/queries
Response: JSON (default), CSV, XLSX
JSON response schema:
{
"data": [
{
"id": ···,
"type": "gobierto_data-queries",
"attributes": {
"name": ···,
"privacy_status": "open"|"closed",
"sql": ···,
"dataset_id": ···,
"user_id": ···,
"links": {
"data": "/api/v1/data/queries/QUERY-ID",
"metadata": "/api/v1/data/queries/QUERY-ID/meta"
}
},
"relationships": {
"dataset": {
"data": {
"id": ···,
"type": "gobierto_data-datasets"
}
},
"user": {
"data": {
"id": ···,
"type": "users"
},
"visualizations": {
"data": []
}
}
}[, ···]
],
"links": {
"new": "/api/v1/data/queries/new",
"visualizations": "/api/v1/data/visualizations",
"self": "/api/v1/data/queries"
}
}
Get the result of a query
GET /api/v1/data/queries/QUERY-ID{.json|.csv|.xlsx}
The result of the query using sql defined for it in the specified format. If the response is requested in JSON format the data is limited to 50 first rows by default.
Parameters:
csv_separator: A string to be used as separator of columns in output. The default column separator is,. There are some keys for special characters:comma: Equivalent to use%2Cor,.semicolon: Equivalent to use%3Bin the query. The use of;produces a wrong csv.colon: Equivalent to use%3Aor:.
data_preview: Default:true. This parameter is only taken into account if the requested format is JSON. Whentrueor not provided the"data"values of the response is limited to the 50 first rows of the query used.
Example request: /api/v1/data/queries/1
Response: JSON (default), CSV, XLSX
JSON response schema:
{
"data": [ 50 first rows of query result unless data_preview=false in the request ],
"meta": {
"duration": ···,
"rows": ···,
"status": ···
},
"links": {
"index": "/api/v1/data/queries",
"new": "/api/v1/data/queries/new",
"visualizations": "/api/v1/data/visualizations?query_id=QUERY-ID",
"metadata": "/api/v1/data/queries/QUERY-ID/meta",
"self": "/api/v1/data/queries/QUERY-ID"
}
}
Get metadata of a query
GET /api/v1/data/queries/QUERY-ID/meta{.json}
Attributes and relationships of the query with QUERY-ID id in JSON format.
Example request: /api/v1/data/queries/1/meta
Response: JSON
Response schema:
{
"data": {
"id": ···,
"type": "gobierto_data-queries",
"attributes": {
"name": ···,
"privacy_status": "open"|"closed",
"sql": ···,
"dataset_id": 6,
"user_id": 90,
"formats": {
"json": "/api/v1/data/queries/QUERY-ID/download.json",
"csv": "/api/v1/data/queries/QUERY-ID/download.csv",
"xlsx": "/api/v1/data/queries/QUERY-ID/download.xlsx"
}
},
"relationships": {
"dataset": {
"data": {
"id": ···,
"type": "gobierto_data-datasets"
}
},
"user": {
"data": {
"id": ···,
"type": "users"
}
},
"visualizations": {
"data": []
}
}
},
"links": {
"index": "/api/v1/data/queries",
"new": "/api/v1/data/queries/new",
"visualizations": "/api/v1/data/visualizations?query_id=QUERY-ID",
"data": "/api/v1/data/queries/QUERY-ID",
"self": "/api/v1/data/queries/QUERY-ID/meta"
}
}
ToDo: Add query result summary attributes and more detailed data of associations
Download query result
GET /api/v1/data/queries/QUERY-ID/download{.json|.csv|.xlsx}
Result of query in specified format. The name of file includes the dataset slug and the query name in its name.
Example request: /api/v1/data/queries/1/download.json
Response: JSON, CSV, XLSX
Prepare to create a new query
GET /api/v1/data/queries/new{.json}
Attributes to create a new query. The JSON returned by this request can be used (with valid values for attributes) in the body of the next request. If the request includes a valid user's token the user_id attribute is filled with the id of the user.
Example request: /api/v1/data/queries/new
Response: JSON
Response schema:
{
"data": {
"type": "gobierto_data-queries",
"attributes": {
"name_translations": {
"en": null,
"es": null
},
"privacy_status": "open",
"sql": null,
"dataset_id": null,
"user_id": ···
},
"relationships": {
"dataset": {
"data": null
},
"user": {
"data": ···
},
"visualizations": {
"data": []
}
}
},
"links": {
"index": "/api/v1/data/queries",
"visualizations": "/api/v1/data/visualizations",
"self": "/api/v1/data/queries/new"
}
}
Create new query
POST /api/v1/data/queries{.json}
This request is used to create a new query. This action is allowed only to authenticated users.
The user of the resource is obtained with the token.
Example request: /api/v1/data/queries with body:
{
"data": {
"type": "gobierto_data-queries",
"attributes": {
"name_translations": {
"en": "Query from API",
"es": "Query desde la API"
},
"privacy_status": "open",
"sql": "select * from dataset_table",
"dataset_id": 6
}
}
}
Response:
- If the resource could be created: JSON with the resource serialized in the same way that
metaaction with status201 Created - If the resource couldn't be created: JSON with
errorskey and a list of errors with status422 Unprocessable Entity
Response schema:
{
"data": {
"id": ···,
"type": "gobierto_data-queries",
"attributes": {
"name_translations": { ··· },
"privacy_status": "open"|"closed",
"sql": ···,
"dataset_id": ···,
"user_id": ···
},
"relationships": {
"dataset": {
"data": {
"id": ···,
"type": "gobierto_data-datasets"
}
},
"user": {
"data": {
"id": ···,
"type": "users"
}
},
"visualizations": {
"data": []
}
}
},
"links": {
"index": "/api/v1/data/queries",
"new": "/api/v1/data/queries/new",
"visualizations": "/api/v1/data/visualizations?query_id=QUERY-ID",
"data": "/api/v1/data/queries/QUERY-ID",
"self": "/api/v1/data/queries/QUERY-ID/meta"
}
}
Update a query
PUT|PATCH /api/v1/data/queries/QUERY-ID{.json}
This request is used to update an existing query. This action is allowed only to authenticated users using the token of the owner of the resource.
The user_id and dataset_id, can't be changed for an existing query via API, so the values sent in the body for these attributes are ignored.
Example request: /api/v1/data/queries/1 with body:
{
"data": {
"type": "gobierto_data-queries",
"attributes": {
"name_translations": {
"en": "Query from API updated",
"es": "Query desde la API updated"
},
"privacy_status": "closed",
"sql": "select * from dataset_table limit 2"
}
}
}
Response:
- If the resource could be updated: JSON with the changed resource serialized in the same way that
metaaction with status200 OK - If the resource couldn't be updated: JSON with
errorskey and a list of errors with status422 Unprocessable Entity
Response schema:
{
"data": {
"id": ···,
"type": "gobierto_data-queries",
"attributes": {
"name_translations": { ··· },
"privacy_status": "open"|"closed",
"sql": ···,
"dataset_id": ···,
"user_id": ···
},
"relationships": {
"dataset": {
"data": {
"id": ···,
"type": "gobierto_data-datasets"
}
},
"user": {
"data": {
"id": ···,
"type": "users"
}
},
"visualizations": {
"data": [
{
"id": ···,
"type": "gobierto_data-visualizations"
}[, ···]
]
}
}
},
"links": {
"index": "/api/v1/data/queries",
"new": "/api/v1/data/queries/new",
"visualizations": "/api/v1/data/visualizations?query_id=QUERY-ID",
"data": "/api/v1/data/queries/QUERY-ID",
"metadata": "/api/v1/data/queries/QUERY-ID/meta"
}
}
Delete a query
DELETE /api/v1/data/queries/QUERY-ID{.json}
This request is used to delete an existing query. This action is allowed only to authenticated users using the token of the owner of the resource. If the resource exists, it's removed a an empty response with status 204 No Content is returned.
Example request: /api/v1/data/queries/1
Response: empty with status 204 No Content
Visualizations
List visualizations
GET /api/v1/data/visualizations{.json|.csv|.xlsx}
List of all open visualizations of the site in specified format.
filter: The results can be filtered by:dataset_id: id of the dataset of the query the visualizations belongs to. Syntax:filter[dataset_id]=DATASET-ID.query_id: id of the query the visualizations belongs to. Syntax:filter[query_id]=QUERY-ID.user_id: id of the user the visualizations belongs to. Syntax:filter[user_id]=USER-ID. If the request is authenticated with token and the token belongs to the user withUSER-ID, all visualizations are listed, including closed ones.
order: The results can be ordered bycreated_atandupdated_at. For both attributes the syntax is the same:order[ATTRIBUTE]=ORDER_KEYWORD, where ORDER_KEYWORD can beascordesc.csv_separator: A string to be used as separator of columns in output. The default column separator is,. There are some keys for special characters:comma: Equivalent to use%2Cor,.semicolon: Equivalent to use%3Bin the query. The use of;produces a wrong csv.colon: Equivalent to use%3Aor:.
Example request: /api/v1/data/visualizations?filter[query_id]=1
Response: JSON (default), CSV, XLSX
JSON response schema:
{
"data": [
{
"id": ···,
"type": "gobierto_data-visualizations",
"attributes": {
"name": ···,
"privacy_status": "open"|"closed",
"spec": ···,
"query_id": ···,
"user_id": ···,
"links": {
"show": "/api/v1/data/visualizations/VISUALIZATION-ID"
}
},
"relationships": {
"query": {
"data": {
"id": ···,
"type": "gobierto_data-queries"
}
},
"user": {
"data": {
"id": ···,
"type": "users"
}
}
}
}[, ···]
],
"links": {
"new": "/api/v1/data/visualizations/new",
"self": "/api/v1/data/visualizations"
}
}
Get the configuration of a visualization
GET /api/v1/data/visualizations/VISUALIZATION-ID{.json}
Show action: Attributes of the visualization with VISUALIZATION-ID id in JSON format.
Parameters: -
Example request: /api/v1/data/visualizations/1
Response: JSON
JSON response schema:
{
"data": {
"id": ···,
"type": "gobierto_data-visualizations",
"attributes": {
"name": ···,
"privacy_status": "open"|"closed",
"spec": ···,
"sql": ···,
"query_id": ···,
"dataset_id": ···,
"user_id": ···
},
"relationships": {
"query": {
"data": {
"id": ···,
"type": "gobierto_data-queries"
}
},
"dataset": {
"data": {
"id": ···,
"type": "gobierto_data-datasets"
}
},
"user": {
"data": {
"id": ···,
"type": "users"
}
}
}
},
"links": {
"index": "/api/v1/data/visualizations",
"new": "/api/v1/data/visualizations/new",
"self": "/api/v1/data/visualizations/VISUALIZATION-ID"
}
}
Prepare to create a new visualization
GET /api/v1/data/visualizations/new{.json}
Attributes to create a new visualization. The JSON returned by this request can be used (with valid values for attributes) in the body of the next request. If the request includes a valid user's token the user_id attribute is filled with the id of the user.
Example request: /api/v1/data/visualizations/new
Response: JSON
Response schema:
{
"data": {
"type": "gobierto_data-visualizations",
"attributes": {
"name_translations": {
"ca": null,
"es": null
},
"privacy_status": "open",
"spec": null,
"sql": null,
"query_id": null,
"dataset_id": null,
"user_id": null
},
"relationships": {
"query": {
"data": null
},
"dataset": {
"data": null
},
"user": {
"data": null
}
}
},
"links": {
"index": "/api/v1/data/visualizations",
"self": "/api/v1/data/visualizations/new"
}
}
Create a new visualization
POST /api/v1/data/visualizations{.json}
This request is used to create a new visualization. This action is allowed only to authenticated users. The presence of a dataset is mandatory to create the visualization. Optionally a query_id can be provided. If a valid query_id is provided the dataset is inferred from it. Also a sql param with a query content of a query can be sent.
The user of the resource is obtained with the token.
Example request: /api/v1/data/visualizations with body:
{
"data": {
"type": "gobierto_data-visualizations",
"attributes": {
"name_translations": {
"en": "New visualization",
"es": "Nueva visualizacion"
},
"privacy_status": "open",
"spec": {
"a": 1,
"b": 2
},
"sql": "select * from dataset_table limit 2",
"dataset_id": 1
},
}
}
Response:
- If the resource could be created: JSON with the resource serialized in the same way that show action with status
201 Created - If the resource couldn't be created: JSON with
errorskey and a list of errors with status422 Unprocessable Entity
Response schema:
{
"data": {
"id": ···,
"type": "gobierto_data-visualizations",
"attributes": {
"name_translations": { ··· },
"privacy_status": "open"|"closed",
"spec": ···,
"query_id": ···,
"user_id": ···
},
"relationships": {
"query": {
"data": null
},
"dataset": {
"data": {
"id": ···,
"type": "gobierto_data-datasets"
}
},
"user": {
"data": {
"id": ···,
"type": "users"
}
}
}
}
},
"links": {
"index": "/api/v1/data/visualizations",
"new": "/api/v1/data/visualizations/new",
"self": "/api/v1/data/visualizations/VISUALIZATION-ID"
}
}
Update a visualization
PUT|PATCH /api/v1/data/visualizations/VISUALIZATION-ID{.json}
This request is used to update an existing visualization. This action is allowed only to authenticated users using the token of the owner of the resource.
The user_id and query_id, can't be changed for an existing visualization via API, so the values sent in the body for these attributes are ignored.
Example request: /api/v1/data/visualizations/1 with body:
{
"data": {
"id": ···,
"type": "gobierto_data-visualizations",
"attributes": {
"name_translations": {
"en": "Visualization changed",
"es": "Visualización cambiada"
},
"privacy_status": "open",
"spec": {
"a": "A",
"b": "B",
"c": "C"
},
"query_id": 1,
"user_id": 90
},
}
}
Response:
- If the resource could be updated: JSON with the changed resource serialized in the same way that
showaction with status200 OK - If the resource couldn't be updated: JSON with
errorskey and a list of errors with status422 Unprocessable Entity
Response schema:
{
"data": {
"id": ···,
"type": "gobierto_data-visualizations",
"attributes": {
"name_translations": { ··· },
"privacy_status": "open"|"closed",
"spec": ···,
"sql": ···,
"query_id": ···,
"dataset_id": ···,
"user_id": ···
},
"relationships": {
"query": {
"data": {
"id": ···,
"type": "gobierto_data-queries"
}
},
"dataset": {
"data": {
"id": ···,
"type": "gobierto_data-datasets"
}
},
"user": {
"data": {
"id": ···,
"type": "users"
}
}
}
},
"links": {
"index": "/api/v1/data/visualizations",
"new": "/api/v1/data/visualizations/new",
"show": "/api/v1/data/visualizations/VISUALIZATION-ID"
}
}
Delete a visualization
DELETE /api/v1/data/visualizations/VISUALIZATION-ID{.json}
This request is used to delete an existing visualization. This action is allowed only to authenticated users using the token of the owner of the resource. If the resource exists, it's removed a an empty response with status 204 No Content is returned
Example request: /api/v1/data/visualizations/1
Response: empty with status 204 No Content
Favorites
List favorites of a resource
GET /api/v1/data/datasets/DATASET-SLUG/favorites{.json}
GET /api/v1/data/queries/QUERY-ID/favorites{.json}
GET /api/v1/data/visualizations/VISUALIZATION-ID/favorites{.json}
A user can favorite multiple resource types, as datasets, queries and visualizations. Each resource has an endpoint to get favorites of a user of the resource itself and dependent subresources if exist. If a request is sent to these endpoints with a valid authentication token and no filter params by user_id are provided, the returned data is the favorites of the user the token belongs to.
The data section contains a list of favorites including the class and serialized attributes of each favorited resource.
Meta section has some extra information:
self_favorited: Whether the resource of the endpoint is favorited or not by the user.dataset_favorited: Only present if the resource of the endpoint belongs to a dataset (queries or visualizations). Whether the dataset the resource of the endpoint belongs to is favorited or not by the user.query_favorited: Only present if the resource of the endpoint belongs to a query (visualizations). Whether the query the resource of the endpoint belongs to is favorited or not by the user.
Parameters:
filter: The results can be filtered by:user_id: id of the user who favorited the resource and subresources. Syntax:filter[user_id]=USER-ID.
Example request: /api/v1/data/query/1/favorites
Response: JSON
Response schema:
{
"data": [
{
"id": ···,
"type": "gobierto_data-favorites",
"attributes": {
"user_id": ···,
"favorited_type": "GobiertoData::Query" | "GobiertoData::Visualization",
"favorited_id": ···,
"favorited": {
"id": ···,
···
},
"created_at": ···
}
}[, ···]
],
"links": {
"new": "/api/v1/data/queries/1/favorite/new",
"self": "/api/v1/data/queries/1/favorites"
},
"meta": {
"self_favorited": true | false,
"dataset_favorited": true | false
}
}```
----
## Create new favorite
`POST` **/api/v1/data/datasets/DATASET-SLUG/favorite{.json}**
`POST` **/api/v1/data/queries/QUERY-ID/favorite{.json}**
`POST` **/api/v1/data/visualizations/VISUALIZATION-ID/favorite{.json}**
Request to create a new favorite of a resource. This action is allowed only to [authenticated users](https://gobierto.readme.io/docs/authentication). The favorited resource is get from the path, and the user from the token.
Example request: `/api/v1/data/datasets/presupuestos/favorite` with empty body.
Response:
* If the favorite could be created: JSON with the favorite serialized with status `201 Created`
* If the resource couldn't be created: JSON with `errors` key and a list of errors with status `422 Unprocessable Entity`. Errors are produced when the resource has been already favorited by the user
Response schema:
```json
{
"data": {
"id": ···,
"type": "gobierto_data-favorites",
"attributes": {
"user_id": ···,
"favorited_type": "GobiertoData::Dataset",
"favorited_id": ···,
"favorited": {
"id": ···,
...
},
"created_at": ···
},
"relationships": {
"user": {
"data": { ··· }
},
"favorited": {
"data": { ··· }
}
}
},
"links": {
"index": "/api/v1/data/datasets/presupuestos/favorites"
}
}
Delete a favorite
DELETE /api/v1/data/datasets/DATASET-SLUG/favorite{.json}
DELETE /api/v1/data/queries/QUERY-ID/favorite{.json}
DELETE /api/v1/data/visualizations/VISUALIZATION-ID/favorite{.json}
Request to delete an existing favorite. This action is allowed only to authenticated users. The favorited resource is get from the path, and the user from the token. If the resource is not favorited by the user a 401 Unauthorized response is returned.
Example request: /api/v1/data/datasets/presupuestos/favorite
Response: empty with status 204 No Content
Updated about 1 year ago
Checkout some API call examples and the schema of a dataset in the following links: