Open Data City of Liege Connector Integration

info@ismena.com

Open Data City of Liege

Connector Details

Type

Virtual machines, Single VM , BYOL

Runs on

Google Compute Engine

Last Update

24 October, 2024

Category

The Open Data City of Liege Connector facilitates seamless integration with the Open Data City of Liege API (Explore API v2.1), a service providing access to all open datasets available through the platform. The API is organized around REST principles and is designed for data retrieval, with all action points providing structured data responses. The connector acts as a proxy to streamline data retrieval, supporting actions for querying datasets, catalog exports, and dataset records.

Integration Overview

This document provides a detailed guide for each integration point, its purpose, configuration, and workflow support using the Open Data City of Liege API Connector.

Supported Integration Action Points

getDatasets: Retrieve available datasets from the catalog.
listExportFormats: List available export formats for the catalog.
exportDatasets: Export the catalog in a desired format.
exportCatalogCSV: Export the catalog in CSV format with specific parameters.
exportCatalogDCAT: Export the catalog in RDF/XML (DCAT) format.
getDatasetsFacets: Enumerate facet values for datasets in the catalog.
getRecords: Query records for a specific dataset.
listDatasetExportFormats: List available export formats for a specific dataset.
exportRecords: Export a dataset’s records in a desired format.
exportRecordsCSV: Export a dataset’s records in CSV format with specific parameters.
exportRecordsParquet: Export a dataset’s records in Parquet format with specific parameters.
exportRecordsGPX: Export a dataset’s records in GPX format with specific parameters.
getDataset: Return information, metadata, and available endpoints for a specified dataset.
getRecordsFacets: Enumerate facet values for records within a specified dataset.
getDatasetAttachments: Return a list of all available attachments for a dataset.
getRecord: Read a single dataset record based on its identifier.

Detailed Integration Documentation

2.1 Get Datasets Retrieval

Action	getDatasets
Purpose	Retrieves a list of available datasets from the catalog.
Configuration	Ensure the connector is configured with the base URL via the CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL environment variable. The connector must also be configured for API key authentication using the apikey query parameter.
Parameters	Required: None Optional: select where order_by limit (default: 10, max: 100 without group_by, 20000 with group_by) offset (default: 0) refine exclude lang (default: "fr") timezone group_by include_links include_app_metas
Output	Successful: JSON object containing: total_count: Total number of datasets. results: Array of dataset objects (metadata, fields, links). Failure: Returns error details (e.g., 400 Bad Request, 401 Unauthorized, 429 Too Many Requests, 500 Internal Server Error).
Workflow Example	Configure the connector with the correct base URL and API key. Execute the getDatasets action with limit=5 and offset=0. Process the response to display the first 5 available datasets to the user.

2.2 List Catalog Export Formats Retrieval

Action	listExportFormats
Purpose	Retrieves a list of available export formats for the catalog.
Configuration	Ensure the connector is configured with the base URL via the CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL environment variable.
Parameters	Required: None Optional: None
Output	Successful: JSON object containing a list of links representing the available export formats. Failure: Error details (400, 401, 429, 500).
Workflow Example	Execute the listExportFormats action. Review available links to determine supported formats (CSV, JSON, XLSX).

2.3 Export Catalog Retrieval

Action	exportDatasets
Purpose	Exports the catalog in the desired format specified in the path.
Configuration	Ensure the connector is configured with the base URL via CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: format (path) Optional: select, where, order_by, group_by, limit, offset refine, exclude, lang, timezone Notes: format: csv, json, xlsx limit: default -1 (retrieve all records)
Output	Successful: Returns a file in the requested format. Failure: Error details (400, 401, 429, 500).
Workflow Example	Call exportDatasets with format=csv. Download the full catalog for offline analysis.

2.4 Export Catalog in CSV Retrieval

Action	exportCatalogCSV
Purpose	Exports the catalog in CSV format with configurable CSV options.
Configuration	Ensure the connector is configured with the base URL via CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: None Optional: delimiter (default: 😉 list_separator quote_all with_bom (default: true)
Output	Successful: Returns a CSV file. Failure: Error details (400, 401, 429, 500).
Workflow Example	Execute exportCatalogCSV with delimiter="," and with_bom=false. Receive a standard comma-separated CSV without BOM.

2.5 Export Catalog in DCAT Retrieval

Action	exportCatalogDCAT
Purpose	Exports the catalog in RDF/XML following DCAT vocabulary.
Configuration	Ensure the connector is configured via CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: dcat_ap_format (path) Optional: include_exports use_labels_in_exports (default: true)
Output	Successful: Returns RDF/XML file. Failure: Error details (400, 401, 429, 500).
Workflow Example	Execute exportCatalogDCAT with dcat_ap_format=_ap_ch and use_labels_in_exports=false. Receive catalog in DCAT-AP-CH format with field names instead of labels.

2.6 Get Datasets Facets Retrieval

Action	getDatasetsFacets
Purpose	Enumerates facet values for datasets, supporting guided navigation and UI filters.
Configuration	Ensure the connector is configured with the base URL via CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: None Optional: facet refine exclude where timezone
Output	Successful: JSON object containing facet lists (values, count, state). Failure: Error details (400, 401, 429, 500).
Workflow Example	Execute getDatasetsFacets with facet=publisher. Display all publishers and dataset counts for UI filtering.

2.7 Query Dataset Records Retrieval

Action	getRecords
Purpose	Performs a query on the records of a specific dataset.
Configuration	Ensure the connector is configured with the base URL via CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: dataset_id (path) Optional: select, where, group_by, order_by, limit, offset, refine, exclude, lang, timezone, include_links, include_app_metas Notes: limit: default 10, max 100 without group_by, 20000 with group_by
Output	Successful: JSON object with total_count and results array Failure: Error details (400, 401, 429, 500)
Workflow Example	Execute getRecords with dataset_id=geonames-all-cities-with-a-population-1000 and limit=2 Retrieve first two records for display in a geographic application

2.8 List Dataset Export Formats Retrieval

Action	listDatasetExportFormats
Purpose	Retrieves a list of available export formats for a specific dataset.
Configuration	Ensure the connector is configured with the base URL via CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: dataset_id (path) Optional: None
Output	Successful: JSON object with list of links representing dataset export formats Failure: Error details (400, 401, 429, 500)
Workflow Example	Execute listDatasetExportFormats for a specific dataset Review available links to determine supported export formats (e.g., GeoJSON, Parquet)

2.9 Export Dataset Records Retrieval

Action	exportRecords
Purpose	Exports a dataset's records in the desired format specified in the path. Supports group_by parameter.
Configuration	Ensure the connector is configured with the base URL via CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: dataset_id (path), format (path) Optional: select, where, order_by, group_by, limit, refine, exclude, lang, timezone, use_labels, compressed, epsg Notes: format examples: geojson, parquet, xlsx; use_labels default=false; compressed default=false
Output	Successful: File in the specified format Failure: Error details (400, 401, 429, 500)
Workflow Example	Execute exportRecords with dataset_id=geo-data and format=geojson Export full dataset records in GeoJSON format with default EPSG 4326 projection

2.10 Export Dataset Records in CSV Retrieval

Action	exportRecordsCSV
Purpose	Exports a dataset's records in CSV format with configurable CSV options.
Configuration	Ensure the connector is configured with the base URL via CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: dataset_id (path) Optional: delimiter, list_separator, quote_all, with_bom Notes: delimiter default=";"
Output	Successful: CSV file Failure: Error details (400, 401, 429, 500)
Workflow Example	Execute exportRecordsCSV with dataset_id and delimiter="\|" Records are exported using pipe character as field delimiter

2.11 Export Dataset Records in Parquet Retrieval

Action	exportRecordsParquet
Purpose	Exports a dataset's records in Parquet format.
Configuration	Ensure the connector is configured with the base URL via CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: dataset_id (path) Optional: parquet_compression (default: snappy, enum: snappy, zstd)
Output	Successful: Parquet file Failure: Error details (400, 401, 429, 500)
Workflow Example	Execute exportRecordsParquet with dataset_id and parquet_compression=zstd Generates Parquet file with ZSTD compression for efficient storage

2.12 Export Dataset Records in GPX Retrieval

Action	exportRecordsGPX
Purpose	Exports a dataset's records in GPX format (GPS Exchange Format).
Configuration	Ensure the connector is configured with the base URL via CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: dataset_id (path) Optional: name_field, description_field_list, use_extension (default: true)
Output	Successful: GPX file Failure: Error details (400, 401, 429, 500)
Workflow Example	Execute exportRecordsGPX with dataset_id and name_field=location_name Exports data as GPX with location_name as waypoint name

2.13 Show Dataset Information Retrieval

Action	getDataset
Purpose	Returns endpoints, metadata, and field information for a dataset.
Configuration	Ensure connector is configured with CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: dataset_id (path) Optional: select, lang, timezone, include_links, include_app_metas
Output	Successful: JSON object representing dataset, including metas, fields, and _links Failure: Error details (400, 401, 429, 500)
Workflow Example	Execute getDataset with dataset_id Retrieve metadata and field schema for dynamic query form generation

2.14 List Dataset Facets Retrieval

Action	getRecordsFacets
Purpose	Enumerates facet values for records within a dataset, supporting guided navigation.
Configuration	Ensure connector is configured with CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: dataset_id (path) Optional: where, refine, exclude, facet, lang, timezone Notes: facet example: facet=city
Output	Successful: JSON object with array of facets and their counts Failure: Error details (400, 401, 429, 500)
Workflow Example	Execute getRecordsFacets with dataset_id and facet=country Retrieve country list and record counts for a filter dropdown

2.15 List Dataset Attachments Retrieval

Action	getDatasetAttachments
Purpose	Returns a list of all available attachments for a dataset.
Configuration	Ensure connector is configured with CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: dataset_id (path) Optional: None
Output	Successful: JSON object with attachments metadata (MIME type, URL) Failure: Error details (400, 401, 429, 500)
Workflow Example	Execute getDatasetAttachments with dataset_id Display list of associated files for user download

2.16 Read Dataset Record Retrieval

Action	getRecord
Purpose	Reads a single dataset record based on its unique identifier.
Configuration	Ensure connector is configured with CONNECTOR_ENV_OPENDATA_LIEGE_API_BASE_URL.
Parameters	Required: dataset_id (path), record_id (path) Optional: select, lang, timezone
Output	Successful: JSON object representing the single record Failure: Error details (400, 401, 429, 500)
Workflow Example	Execute getRecord with dataset_id and record_id Retrieve full details of a single record for display in a pop-up on a map

Example Workflow

Example Workflow: Open Data Exploration Dashboard

This workflow demonstrates how to use multiple connector actions to power a public data exploration and visualization dashboard.

Retrieve Available Datasets	Use the getDatasets action with select=dataset_id,title to fetch a list of datasets and their titles. Display this list in a selectable menu for users.
List Facets for Filtering	Execute the getRecordsFacets action using the user-selected dataset_id and a field like facet=theme. Populate a filter panel with the returned facet values and their counts.
Query and Visualize Records	Use the getRecords action with the selected dataset_id and include refine and where parameters based on user selections from the facet panel. Process the filtered records and visualize the data (e.g., on a map or chart).
Export Filtered Data	Provide a download option by executing the exportRecords action with the same filters (dataset_id, refine, where) and specifying format=csv. This allows users to download the specific, filtered subset of data they are viewing.

This comprehensive workflow enables applications to provide users with a complete experience for browsing, filtering, visualizing, and exporting data from the City of Liege Open Data catalog, enhancing public access and utility of the information.

Pricing

bill-and-calculator-2023-11-27-05-25-06-utc 1

Request a Quote

Support

For Technical support please contact us on

custom-connectors-support@isolutions.sa

A tech solution company dedicated to providing innovation thus empowering businesses to thrive in the digital age.

Register to Wired for Banking