CESSDA SKG-IF API

A public API for accessing research information from the CESSDA Data Catalogue in an interoperable SKG-IF format.

The CESSDA SKG-IF API provides structured research information using the Scientific Knowledge Graph Interoperability Framework (SKG-IF). Products, persons and organisations are derived from metadata held in the CESSDA Data Catalogue (CDC). The Topics endpoint exposes concepts from the European Language Social Science Thesaurus (ELSST) as SKG-IF Topic entities.

The API is primarily intended for machine-to-machine use, allowing research infrastructures and other services to exchange and reuse information through a common data model and REST-based interface. People can also explore the API directly using the links and examples on this page.

About SKG-IF

SKG-IF is a shared interoperability framework for exchanging information between scientific knowledge graphs and research information systems. It was originally developed by the Research Data Alliance SKG-IF Working Group and has subsequently been developed further in the OSTrails project, including an OpenAPI specification describing the available entities and operations.

SKG-IF provides both a common data model and a practical API specification. It describes six principal entity types and the relationships between them:

• Research Product Literature, research data, software or another type of research output.
• Agent A person, organisation or generic agent associated with another entity, such as a contributor to a research product.
• Grant Funding associated with a project or research product.
• Venue A publication or dissemination venue for a research product.
• Topic A concept or controlled vocabulary term used to describe a research product.
• Data Source The source or storage location from which research information is provided.

Research products form the central part of the model. Other entities are connected to research products and to each other through references. The API representation may also embed selected information directly in a record. For example, a contribution can contain information about the contributing person or organisation, and a topic can contain multilingual labels resolved from a controlled vocabulary.

CESSDA data sources and implementation

The implementation currently exposes products, topics, persons and organisations. Products comprise research data in the CDC and publications related to those datasets. Persons and organisations are derived from the metadata of the research data and related publications. The standalone Topics endpoint exposes ELSST concepts.

Multilingual topic information in Product records

Product records may contain topic information enriched using the CESSDA Vocabulary Service (CVS). When a controlled vocabulary concept contains labels in multiple languages, the labels are grouped under the same topic concept and exposed as language-specific labels within one embedded SKG-IF Topic entity.

For example, one concept may include the Finnish label “Kansainvälinen politiikka ja järjestöt” and the English label “International politics and organisations”. Clients can therefore display the same concept in different languages while retaining a shared concept identifier.

This CVS-based enrichment applies to topic information embedded in Product records. It is distinct from the standalone Topics endpoint, which exposes ELSST concepts.

• CESSDA Vocabulary Service (CVS), accessed through the CESSDA Vocabulary Service API

Documentation

The API is documented using OpenAPI. The documentation is based on the official SKG-IF OpenAPI specification and has been modified only to reflect the implementation status of the CESSDA endpoints.

Endpoints that are not available are labelled “Not yet implemented” next to the endpoint name. Filters that are not applicable or not implemented are shown with a strikethrough.

Source code

The source code for the CESSDA SKG-IF API is publicly available under the Apache License 2.0.

• CESSDA SKG-IF API, available from the CESSDA SKG-IF API GitHub repository

Metadata mappings

The following mappings describe how source metadata and controlled vocabularies are represented in the CESSDA SKG-IF API.

• CDC DDI 2.5 to CESSDA SKG-IF API mapping
• ELSST to CESSDA SKG-IF Topic API mapping
• CESSDA Vocabulary Service to CESSDA SKG-IF Topic API mapping

Identifiers and entity resolution

In SKG-IF, local_identifier acts as the identifier of an entity. The CESSDA implementation uses resolvable w3id.org identifiers where possible and accepts several equivalent identifier forms when retrieving individual entities.

For a research data Product, the canonical SKG-IF local_identifier is a CESSDA w3id.org URL. Opening that URL redirects to the corresponding human-readable record in the CDC. The Products endpoint can resolve the same entity from the SKG-IF local identifier, the full CDC URL, or the underlying CDC identifier.

d9933f903b3b7d0c04fb5f720bc2fc513a17cf432a91d62499629bbea4507ab1

cessda_product_research_data_d9933f903b3b7d0c04fb5f720bc2fc513a17cf432a91d62499629bbea4507ab1

https://w3id.org/cessda/cessda_product_research_data_d9933f903b3b7d0c04fb5f720bc2fc513a17cf432a91d62499629bbea4507ab1

https://datacatalogue.cessda.eu/detail/d9933f903b3b7d0c04fb5f720bc2fc513a17cf432a91d62499629bbea4507ab1

Literature Products, Persons and Organisations follow the same general resolution principle. Persistent identifiers are preferred when they are available in the source metadata because they can identify the same entity across systems. The API therefore prioritises ORCID for persons and ROR for organisations. These full PID URLs can also be supplied to the corresponding single-entity endpoint.

When no suitable external persistent identifier is available, the API uses a generated local identifier. CESSDA w3id.org identifiers for persons and organisations resolve back to the corresponding single-entity endpoint in the CESSDA SKG-IF API.

Endpoints

The API currently exposes endpoints for research products, topics, persons and organisations. Collection endpoints return paginated result sets, while entity endpoints return an individual record identified by its local or persistent identifier.

/products?page=2&page_size=20

Products endpoint

Products include research data from the CDC and literature related to those datasets.

Topics endpoint

The Topics endpoint exposes concepts from ELSST as SKG-IF Topic entities. Topic identifiers can be supplied as escaped or unescaped URLs.

Persons endpoint

Persons represent individual contributors found in Product metadata. A person can be retrieved using an available persistent identifier such as ORCID.

Organisations endpoint

Organisations represent institutions found in Product metadata. An organisation can be retrieved using an available persistent identifier such as ROR.

Filters

Collection endpoints support filters for narrowing result sets. Filters are supplied through the filter query parameter as field:value pairs.

?filter=field:value,otherfield:othervalue

The examples below demonstrate commonly used filters. Consult the OpenAPI documentation for the complete set of filters supported by each endpoint.

Product filters

Topic filters

Person filters

Organisation filters

Search metadata in the response

Collection responses include a meta section describing the current page and the complete result set.

{
  "meta": {
    "local_identifier": "...?page=2&page_size=20",
    "entity_type": "search_result_page",
    "previous_page": {
      "local_identifier": "...?page=1&page_size=20",
      "entity_type": "search_result_page"
    },
    "next_page": {
      "local_identifier": "...?page=3&page_size=20",
      "entity_type": "search_result_page"
    },
    "part_of": {
      "local_identifier": "...",
      "entity_type": "search_result",
      "total_items": 2165,
      "first_page": {
        "local_identifier": "...?page=1&page_size=20",
        "entity_type": "search_result_page"
      },
      "last_page": {
        "local_identifier": "...?page=109&page_size=20",
        "entity_type": "search_result_page"
      }
    }
  }
}

The meta section identifies the current result page and provides links to the previous and next pages when applicable. The part_of object describes the complete result set, including the total number of matching entities and links to its first and last pages.