SDKs overview

The Open Government, Cyprus data portal, data.gov.cy, operates on the Comprehensive Knowledge Archive Network (CKAN) platform. CKAN provides a web-based portal for open data and a robust API for programmatic access to its datasets and metadata. Software Development Kits (SDKs) and libraries for Open Government, Cyprus primarily consist of client libraries designed to interact with this underlying CKAN API. These tools enable developers to automate tasks such as searching for datasets, retrieving dataset metadata, downloading resources, and managing data programmatically without direct web interface interaction. The API supports various data formats, including CSV, JSON, and XML, depending on the dataset publisher's configuration.

Developers utilize these SDKs to build custom applications, dashboards, and research tools that consume public sector data from Cyprus. This approach supports government transparency, academic research, and the creation of value-added services by third-party developers. The API adheres to RESTful principles, making it accessible from a wide range of programming languages through standard HTTP requests. While there isn't a proprietary SDK developed specifically by the Cypriot government, the widespread adoption of CKAN means that off-the-shelf CKAN client libraries serve as the de facto SDKs for this portal. These libraries encapsulate the complexities of API authentication, request formatting, and response parsing, offering a higher level of abstraction for developers.

Official SDKs by language

Given that the Open Government, Cyprus portal is built on CKAN, the primary 'official' SDKs are the well-maintained and widely used CKAN client libraries. These libraries are developed and supported by the broader CKAN community, ensuring compatibility and ongoing development. The most prominent and officially recommended client library for interacting with CKAN APIs is for Python.

The CKAN API itself is well-documented, providing a clear interface for developers to build their own client implementations in any language if existing libraries do not meet specific needs. The Open Government, Cyprus API documentation details the available endpoints, request parameters, and response structures, which are standard across CKAN installations. This standardization facilitates the use of generic CKAN client libraries.

Here's a table outlining the primary official SDK/client library for CKAN, which is applicable to Open Government, Cyprus:

Language Package Name Install Command Maturity
Python ckanapi pip install ckanapi Stable, widely used

The ckanapi Python library provides a comprehensive interface for interacting with any CKAN instance, including the Open Government, Cyprus portal. It handles API key management, request signing (if required by specific CKAN configurations), and parsing of JSON responses into Python objects. This significantly reduces the boilerplate code developers would need to write for direct HTTP requests. For more details on the ckanapi library, developers can refer to its official GitHub repository.

Installation

Installation of the ckanapi Python library is performed using pip, the standard package installer for Python. This process is straightforward and typically involves a single command.

Prerequisites

  • Python: Ensure you have Python 3.6 or newer installed on your system. You can verify your Python version by running python --version or python3 --version in your terminal. For detailed installation instructions, refer to the official Python downloads page.
  • pip: pip is usually bundled with Python installations. If not, you can install it following the pip installation guide.

Steps for ckanapi installation

  1. Open your terminal or command prompt.
  2. Run the installation command:
    pip install ckanapi

    This command will download the ckanapi package and its dependencies from the Python Package Index (PyPI) and install them into your Python environment. You may consider using a Python virtual environment to manage project dependencies, which is a recommended practice to avoid conflicts between different projects.

  3. Verify installation (optional):
    After installation, you can verify that ckanapi is installed by opening a Python interpreter and attempting to import the library: 
    import ckanapi
print(ckanapi.__version__)
    If no error occurs and a version number is printed, the installation was successful.

For other languages, while there isn't a universally recognized 'official' client library directly analogous to ckanapi, developers can leverage standard HTTP client libraries available in their respective languages (e.g., requests in Python, Axios in JavaScript, HttpClient in C#) to interact with the CKAN API. This involves constructing HTTP GET/POST requests and parsing JSON responses manually, following the specifications laid out in the Open Government, Cyprus API documentation.

Quickstart example

This quickstart example demonstrates how to use the ckanapi Python library to interact with the Open Government, Cyprus data portal. We will perform a simple task: listing available datasets.

Example: Listing datasets

First, ensure you have ckanapi installed as described in the Installation section.

import ckanapi

# Initialize the CKAN API client
# The base URL for the Open Government, Cyprus data portal API
ckan_url = 'https://www.data.gov.cy/'
ua = ckanapi.RemoteCKAN(ckan_url)

print(f"Connecting to CKAN instance at: {ckan_url}")

try:
    # Use the 'package_list' action to get a list of dataset IDs
    # The 'limit' parameter can be used to control the number of results
    dataset_ids = ua.action.package_list(limit=10)
    
    print(f"\nFound {len(dataset_ids)} dataset IDs (limited to 10):")
    for dataset_id in dataset_ids:
        print(f"- {dataset_id}")

    # To get details for a specific dataset, you can use 'package_show'
    if dataset_ids:
        first_dataset_id = dataset_ids[0]
        print(f"\nFetching details for the first dataset: {first_dataset_id}")
        dataset_details = ua.action.package_show(id=first_dataset_id)
        
        print(f"Dataset Title: {dataset_details['title']}")
        print(f"Dataset Description: {dataset_details['notes'][:150]}...") # Truncate description
        print(f"Number of Resources: {len(dataset_details['resources'])}")
        
        if dataset_details['resources']:
            print(f"First Resource URL: {dataset_details['resources'][0]['url']}")

except ckanapi.errors.CKANAPIError as e:
    print(f"An API error occurred: {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

Explanation:

  • ckanapi.RemoteCKAN(ckan_url): This line creates an instance of the RemoteCKAN class, pointing it to the base URL of the Open Government, Cyprus data portal. All subsequent API calls will be made through this instance.
  • ua.action.package_list(limit=10): This calls the package_list action of the CKAN API. This action returns a list of all dataset (package) identifiers. We've added a limit=10 parameter to retrieve only the first 10 dataset IDs for brevity.
  • ua.action.package_show(id=first_dataset_id): This calls the package_show action, which retrieves detailed metadata for a specific dataset identified by its ID. The result is a dictionary containing various fields like title, notes (description), and resources (the actual data files or links).
  • Error Handling: The try...except blocks are included to catch potential ckanapi specific errors (e.g., network issues, invalid API calls) or other general exceptions, ensuring the script handles failures gracefully.

This example provides a fundamental understanding of how to programmatically access and retrieve information from the Open Government, Cyprus data portal using its underlying CKAN API via a Python client library. For more advanced operations, such as filtering datasets, searching with keywords, or accessing specific data resources, refer to the comprehensive Open Government, Cyprus API documentation and the ckanapi library's documentation.

Community libraries

Beyond the official or widely adopted CKAN client libraries like ckanapi, the open-source nature of CKAN has fostered a community of developers who create tools and libraries in various programming languages to interact with CKAN instances. While Open Government, Cyprus does not specifically endorse a set of community-contributed libraries, any library designed to interface with a standard CKAN API should be compatible.

Developers exploring options outside of the primary Python client often look for libraries that abstract HTTP requests and JSON parsing in their preferred language. Examples of such community efforts might include:

  • JavaScript/Node.js Clients: While not a single official library, several community-driven Node.js packages exist on npm for interacting with CKAN APIs. These often wrap common HTTP clients like node-fetch or axios to provide a more structured way to call CKAN endpoints. Developers would typically search npm for ckan client or similar terms to find suitable options.
  • R Packages: For data scientists and statisticians, R packages designed for open data portals or specific CKAN interactions might be available on CRAN or GitHub. These packages aim to integrate CKAN data retrieval directly into R workflows for analysis and visualization.
  • Ruby Gems: Ruby developers might find gems that offer CKAN API client functionalities, often simplifying request construction and response handling in a Ruby-idiomatic way.

When considering community libraries, it is important to evaluate several factors:

  • Maintenance Status: Check the last commit date, issue tracker activity, and pull request history to gauge how actively the library is maintained.
  • Documentation: Comprehensive and clear documentation is crucial for understanding how to use the library effectively and troubleshoot issues.
  • Community Support: Look for evidence of an active user base, such as forums, Stack Overflow tags, or GitHub discussions, where you can seek help or contribute.
  • API Coverage: Ensure the library supports the specific CKAN API actions and data structures you intend to use.
  • Dependencies: Review the library's dependencies to ensure they are compatible with your project's existing stack and do not introduce security vulnerabilities or conflicts.

Developers are encouraged to review the general CKAN API documentation, which provides the foundational knowledge for interacting with any CKAN instance, regardless of the client library used. This understanding empowers developers to choose or even build their own lightweight client if existing options do not perfectly align with their project requirements. The open-source community around CKAN is a valuable resource for finding, evaluating, and contributing to these client libraries.