Skip to main content

Catalog identifier

Purpose​

In the Dateno API, the term catalog identifier appears both in API paths and in metadata fields. This page explains how the catalog_id path parameter relates to the uid and id fields of a catalog.

Unless explicitly stated otherwise, when the API documentation refers to a “catalog ID”, it means the catalog unique identifier (uid).

For details about the unique identifier itself, see:

catalog_id in API paths​

The main endpoint that accepts a catalog ID is:

  • GET /registry/catalog/{catalog_id}

In all current versions of the Dateno API, the {catalog_id} path parameter must be set to the catalog uid (the unique identifier), for example:

GET /registry/catalog/cdi00000310?apikey=YOUR_API_KEY
Host: api.dateno.io

To discover catalog IDs programmatically:

  • Call GET /registry/search/catalogs/?limit=... to list catalogs.
  • Read the uid field from each item in the data array.
  • Use this uid value as {catalog_id} in subsequent calls to /registry/catalog/{catalog_id}.

Relationship between uid and id​

A catalog card returned by GET /registry/catalog/{catalog_id} contains both a uid and an id field:

{
    "id": "openalbertaca",
    "uid": "cdi00000310",
    "name": "Government of Alberta open datasets",
    "link": "https://open.alberta.ca",
    "..."
}

These fields serve different purposes:

  • uid – the primary, stable catalog identifier
    • globally unique within the Dateno catalog registry;
    • remains stable over time, even if catalog metadata changes;
    • used as {catalog_id} in API paths;
    • recommended identifier to store in your own systems.
  • id – an internal, slug-like identifier
    • derived from the catalog host or name (e.g. openalbertaca);
    • used in some internal URLs and diagnostic tools;
    • not guaranteed to remain stable over time;
    • not accepted as {catalog_id} in API paths.

Where catalog IDs appear​

Catalog identifiers appear in several API structures:

  • In catalog search results (/registry/search/catalogs/) as the uid field of each catalog summary.
  • In catalog cards returned by /registry/catalog/{catalog_id} as both uid and id.
  • In dataset metadata, in the source.uid field of dataset cards and dataset descriptors, linking datasets back to their source catalogs.

To learn more about the unique identifier format and behaviour, see: