Reference data as a Services (RDaaS) - API User Guide

Produced by: Center for statistical data standards

Table of contents

Revision history
Purpose of Document
Summary
Access and availability
Technology
Definitions
Application Programming Interface (API) methods and examples:
Concordances
- Map Types

Revision history

Revision history
Date	Version	Revision details
June 1, 2022	1.0	First release of RDaaS User Guide

Purpose of Document

The purpose of this document is to provide users with a guide to the Reference Data as a Service (RDaaS), which has been made accessible through the Government of Canada API (Application Programming Interface) Store.

Summary

The Reference Data as a Service (RDaaS) is a list of codesets, classifications and concordances that are used within Statistics Canada and shared to help harmonise data for better interdepartmental data integration and analysis. This RDaaS initiative is meant to share Statistics Canada's reference data with everyone that would like to facilitate & harmonise data for analysis between Government of Canada and its data partners.

Access and availability

Before you can use an Application Programming Interface (API), you must subscribe to an API plan. The plan determines whether approvals are required and the frequency of API calls that your application can make. Once your application is subscribed to a plan, the application is assigned a unique User Key. You must use this User Key when you call an API. This API follows the Terms and Conditions of the Government of Canada API Store.

Data updates take place on a regular basis, we are in the process of including new ones regularly.

The request limit is 100 hits per minute per user. The maximum number of records that can be extracted per query is 100.

Technology

Hyper Text Transfer Protocol Secure (HTTPS) is a standard way of communicating across the Web and includes methods such as GET and POST used with the web service.

The implementation is a RESTful (built using representational state transfer [REST] architecture) web data service over HTTPS protocol, which will return data in JSON (JavaScript Object Notation) language.

REST is an architectural style that specifies constraints, such as the uniform interface, that if applied to a web service induce desirable properties, such as performance, scalability and modifiability, which enable services to work best on the Web.

Definitions

These Application Programming Interface (API) will give you full list of codesets in the language asked. Here are the classifications and codesets that are getting included and available for general consumptions: Definitions, data sources and methods (statcan.gc.ca). An example of a classification you can find is Gender where you will be able to download through this API the following information: Classification of gender (statcan.gc.ca).

Application Programming Interface (API) methods and examples:

We list numerous types of methods for the Application Programming Interface (API) here:

Search

RDaaS search functionality provides users with the ability to search for the resources they are looking for based on a variety of parameters. Each type of resource will have an endpoint where the actual search is performed, along with the potential for supplemental endpoints that can be used to retrieve user specific parameters to use in the search. These parameters may change based on the user's role.

Search classifications

Searches and filters classifications. Text searching is applied to the classification names and and descriptions. The applicable filters can be found from the get classification search filters method. This search supports paging, and a offset and limit can be specified.

Search classifications - more information

Get URL:
/search/classifications

Parameters:

Name: Description
limit integer (query): the number of results to return; optional, 10 by default, 500 maximum
Default value: 10
q string (query): the search text; optional, omit to search all
start integer (query): the start position for the results returned; optional, 0 (start at first result) by default
Default value: 0
audience string (query): Although this Swagger UI does not allow for it, a parameter can be repeated to filter on more than one value at a time.
Note that the values shown here may not be available to all users. See the corresponding /filters method for this to determine which filter values are applicable to you.
Available values: PUBLIC, INTERNAL, SYSTEM, IATD
status string (query): Although this Swagger UI does not allow for it, a parameter can be repeated to filter on more than one value at a time.
Note that the values shown here may not be available to all users. See the corresponding /filters method for this to determine which filter values are applicable to you.
Available values: DEFINED, VERIFIED, PENDING, APPROVED, RELEASED, WITHDRAWN, RETIRED, ARCHIVED

Response Code:
200- Search classifications.

Example:
This call will return the first 10 classifications available where you can find the id to be used in other calls.

Call:
https://rdaas-statcan.dev.api.canada.ca:443/search/classifications?limit=10

Results:

{
  "results": {
    "@context": "https://https://rdaas-statcan.dev.api.canada.ca/context/classification-search",
    "@graph": [
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/classification/JaHUm1ufHV2ug8te",
        "name": "Broad Economics Categories Rev.5",
        "abbreviation": "BEC Rev.5",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-04-09T19:42:52.000Z",
        "validFrom": "2017-01-01T05:00:00.000Z",
        "validTo": null,
        "codeCount": 176,
        "levelCount": 5
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/classification/f62FzFYfkIvjxbV3",
        "name": "Canadian Export Harmonized System Classification",
        "abbreviation": "HS EXPORT",
        "versionNumber": "2022.1.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2022-01-27T15:03:33.000Z",
        "validFrom": "2022-01-01T05:00:00.000Z",
        "validTo": null,
        "codeCount": 14379,
        "levelCount": 7
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/classification/uUvCKHrQkO0hsZT7",
        "name": "Canadian Import Harmonized System Classification",
        "abbreviation": "HS IMPORT",
        "versionNumber": "2022.1.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2022-04-01T14:49:45.000Z",
        "validFrom": "2022-01-01T05:00:00.000Z",
        "validTo": null,
        "codeCount": 18461,
        "levelCount": 6
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/classification/f6Qv5lajXNnuRprv",
        "name": "Currency - Trade",
        "abbreviation": "Currency - Trade",
        "versionNumber": "2.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-04-09T19:48:25.000Z",
        "validFrom": "2017-03-01T05:00:00.000Z",
        "validTo": null,
        "codeCount": 12,
        "levelCount": 1
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/classification/Zfa6DtGt9zxLNLlg",
        "name": "Foreign Port - US",
        "abbreviation": "Foreign Port - US",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-04-09T21:27:39.000Z",
        "validFrom": "2003-01-01T05:00:00.000Z",
        "validTo": null,
        "codeCount": 219,
        "levelCount": 1
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/classification/MAPNwNaJqcTbdOjz",
        "name": "Mode of Transport - CBSA",
        "abbreviation": "MOT - CBSA",
        "versionNumber": "2.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-04-09T21:15:15.000Z",
        "validFrom": "2011-04-01T04:00:00.000Z",
        "validTo": null,
        "codeCount": 8,
        "levelCount": 1
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/classification/Y8mnDR84EAeqYqHD",
        "name": "Mode of Transport - Trade",
        "abbreviation": "MOT - Trade",
        "versionNumber": "4.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-04-09T21:15:08.000Z",
        "validFrom": "2011-04-01T04:00:00.000Z",
        "validTo": null,
        "codeCount": 8,
        "levelCount": 1
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/classification/zehGedMZK4pBtAbu",
        "name": "Mode of Transport - US",
        "abbreviation": "MOT - US",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-04-09T21:15:18.000Z",
        "validFrom": "2003-01-01T05:00:00.000Z",
        "validTo": null,
        "codeCount": 18,
        "levelCount": 1
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/classification/e6kWFUu1JiNruS1q",
        "name": "North American Industry Classification System (NAICS) Canada - Trade Variant",
        "abbreviation": "NAICS - Trade",
        "versionNumber": "2017.2.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-04-09T21:17:05.000Z",
        "validFrom": "2017-01-01T05:00:00.000Z",
        "validTo": null,
        "codeCount": 2084,
        "levelCount": 5
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/classification/oEV57hjhxU9wOvok",
        "name": "North American Product Classification System (NAPCS) Canada 2017 - Trade Variant",
        "abbreviation": "NAPCS 2017 - Trade",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-04-09T21:19:58.000Z",
        "validFrom": "2017-01-01T05:00:00.000Z",
        "validTo": null,
        "codeCount": 2670,
        "levelCount": 6
      }
    ]
  },
  "found": 307,
  "start": 0,
  "limit": 10,
  "facets": {
    "status": {
      "RETIRED": 286,
      "RELEASED": 21
    },
    "audience": {
      "PUBLIC": 307
    }
  }
}

Classification search filters

This will return a list of filters and the values that can be used on them when searching for classifications. The can be used as query parameters on any search request. For example, if the there is a filter named "bank" with values "A", "B", and "C", query parameters can be added to any search request to filter the results based on these values. For instance, to filter on "bank" "A" and "B", one could append ?bank=A&bank=B to the query url. It is worth noting that these filers will also be included as facet counts in all search results.

Classification search filters - more information

Get URL:
/search/classifications/filters.

Parameters:
None

Response Code:
200- Search classifications.

Example:
This call will return a list a classification filters that can be used in other calls.

Call:
https://rdaas-statcan.dev.api.canada.ca:443/search/classifications/filters

Results:

[
  {
    "parameter": "status",
    "values": [
      "RELEASED",
      "RETIRED",
      "ARCHIVED"
    ]
  },
  {
    "parameter": "audience",
    "values": [
      "PUBLIC"
    ]
  }
]

Search concordances

Searches and filters concordances. Text searching is applied to the concordance names and and descriptions. The applicable filters can be found from the get concordance search filters method. This search supports paging, and an offset and limit can be specified.

Search concordances - more information

Get URL:
/search/concordances.

Parametrs:

Name: Description
limit integer (query): the number of results to return; optional, 10 by default, 500 maximum
Default value: 10
q string (query): the search text; optional, omit to search all
start integer (query): the start position for the results returned; optional, 0 (start at first result) by default
Default value: 0
audience string (query): Although this Swagger UI does not allow for it, a parameter can be repeated to filter on more than one value at a time.
Note that the values shown here may not be available to all users. See the corresponding /filters method for this to determine which filter values are applicable to you.
Available values: PUBLIC, INTERNAL, SYSTEM, IATD
status string (query): Although this Swagger UI does not allow for it, a parameter can be repeated to filter on more than one value at a time.
Note that the values shown here may not be available to all users. See the corresponding /filters method for this to determine which filter values are applicable to you.
Available values: DEFINED, VERIFIED, PENDING, APPROVED, RELEASED, WITHDRAWN, RETIRED, ARCHIVED

Response Code:
200- Search concordances.

Example:
This call will return the fisrt 10 concordances available where you can use the id for other calls.

Call:
https://rdaas-statcan.dev.api.canada.ca:443/search/concordances?limit=10

Results:

{
  "results": {
    "@context": "https://https://rdaas-statcan.dev.api.canada.ca/context/concordance-search",
    "@graph": [
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/concordance/wXye8Sprvb6crEas",
        "name": "Canadian Export Harmonized System Classification V2017.4.0 to V2022.1.0",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-12-17T14:24:56.000Z",
        "validFrom": "2022-01-01T05:00:00.000Z",
        "validTo": null,
        "source": "https://https://rdaas-statcan.dev.api.canada.ca/classification/iMIHs0L5XgjCa2Lv",
        "source_name": "Canadian Export Harmonized System Classification",
        "sourceVersionNumber": "2017.4.0",
        "target": "https://https://rdaas-statcan.dev.api.canada.ca/classification/f62FzFYfkIvjxbV3",
        "target_name": "Canadian Export Harmonized System Classification",
        "targetVersionNumber": "2022.1.0"
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/concordance/nWgrMtjNwHChDw5p",
        "name": "Canadian Import Harmonized System Classification V2017.10.0 to V2022.1.0",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-12-17T14:01:55.000Z",
        "validFrom": "2022-01-01T05:00:00.000Z",
        "validTo": null,
        "source": "https://https://rdaas-statcan.dev.api.canada.ca/classification/RX95ZpPbN12QVELg",
        "source_name": "Canadian Import Harmonized System Classification",
        "sourceVersionNumber": "2017.10.0",
        "target": "https://https://rdaas-statcan.dev.api.canada.ca/classification/uUvCKHrQkO0hsZT7",
        "target_name": "Canadian Import Harmonized System Classification",
        "targetVersionNumber": "2022.1.0"
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/concordance/LrI66BxXC8lJBIxw",
        "name": "Currency - Trade V1.0.0 to V2.0.0",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-04-09T19:48:27.000Z",
        "validFrom": null,
        "validTo": null,
        "source": "https://https://rdaas-statcan.dev.api.canada.ca/classification/gccMom29Ed8jteFd",
        "source_name": "Currency - Trade",
        "sourceVersionNumber": "1.0.0",
        "target": "https://https://rdaas-statcan.dev.api.canada.ca/classification/f6Qv5lajXNnuRprv",
        "target_name": "Currency - Trade",
        "targetVersionNumber": "2.0.0"
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/concordance/ZGCPzTXXQ6wUhUWu",
        "name": "Export HS v22.1 to BEC Rev5 - Trade",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-12-17T14:26:11.000Z",
        "validFrom": "2022-01-01T05:00:00.000Z",
        "validTo": null,
        "source": "https://https://rdaas-statcan.dev.api.canada.ca/classification/f62FzFYfkIvjxbV3",
        "source_name": "Canadian Export Harmonized System Classification",
        "sourceVersionNumber": "2022.1.0",
        "target": "https://https://rdaas-statcan.dev.api.canada.ca/classification/JaHUm1ufHV2ug8te",
        "target_name": "Broad Economics Categories Rev.5",
        "targetVersionNumber": "1.0.0"
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/concordance/XlKwJLHfC0afFMzA",
        "name": "Export HS v22.1 to NAICS 2017 - Trade",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-12-17T14:27:26.000Z",
        "validFrom": "2022-01-01T05:00:00.000Z",
        "validTo": null,
        "source": "https://https://rdaas-statcan.dev.api.canada.ca/classification/f62FzFYfkIvjxbV3",
        "source_name": "Canadian Export Harmonized System Classification",
        "sourceVersionNumber": "2022.1.0",
        "target": "https://https://rdaas-statcan.dev.api.canada.ca/classification/e6kWFUu1JiNruS1q",
        "target_name": "North American Industry Classification System (NAICS) Canada - Trade Variant",
        "targetVersionNumber": "2017.2.0"
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/concordance/oMMJwY1zs5TSJxHP",
        "name": "Export HS v22.1 to NAPCS 2017 - Trade",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-12-17T14:28:53.000Z",
        "validFrom": "2022-01-01T05:00:00.000Z",
        "validTo": null,
        "source": "https://https://rdaas-statcan.dev.api.canada.ca/classification/f62FzFYfkIvjxbV3",
        "source_name": "Canadian Export Harmonized System Classification",
        "sourceVersionNumber": "2022.1.0",
        "target": "https://https://rdaas-statcan.dev.api.canada.ca/classification/oEV57hjhxU9wOvok",
        "target_name": "North American Product Classification System (NAPCS) Canada 2017 - Trade Variant",
        "targetVersionNumber": "1.0.0"
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/concordance/ps0XGLhLIlQQ2C4F",
        "name": "Import HS v22.1 to BEC Rev5 - Trade",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-12-17T14:15:24.000Z",
        "validFrom": "2022-01-01T05:00:00.000Z",
        "validTo": null,
        "source": "https://https://rdaas-statcan.dev.api.canada.ca/classification/uUvCKHrQkO0hsZT7",
        "source_name": "Canadian Import Harmonized System Classification",
        "sourceVersionNumber": "2022.1.0",
        "target": "https://https://rdaas-statcan.dev.api.canada.ca/classification/JaHUm1ufHV2ug8te",
        "target_name": "Broad Economics Categories Rev.5",
        "targetVersionNumber": "1.0.0"
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/concordance/mM8lsaCxGbvR6NEZ",
        "name": "Import HS v22.1 to NAICS 2017 - Trade",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-12-17T14:17:59.000Z",
        "validFrom": "2022-01-01T05:00:00.000Z",
        "validTo": null,
        "source": "https://https://rdaas-statcan.dev.api.canada.ca/classification/uUvCKHrQkO0hsZT7",
        "source_name": "Canadian Import Harmonized System Classification",
        "sourceVersionNumber": "2022.1.0",
        "target": "https://https://rdaas-statcan.dev.api.canada.ca/classification/e6kWFUu1JiNruS1q",
        "target_name": "North American Industry Classification System (NAICS) Canada - Trade Variant",
        "targetVersionNumber": "2017.2.0"
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/concordance/Ngk02zSqvLvUYbyd",
        "name": "Import HS v22.1 to NAPCS 2017 - Trade",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-12-17T14:19:20.000Z",
        "validFrom": "2022-01-01T05:00:00.000Z",
        "validTo": null,
        "source": "https://https://rdaas-statcan.dev.api.canada.ca/classification/uUvCKHrQkO0hsZT7",
        "source_name": "Canadian Import Harmonized System Classification",
        "sourceVersionNumber": "2022.1.0",
        "target": "https://https://rdaas-statcan.dev.api.canada.ca/classification/oEV57hjhxU9wOvok",
        "target_name": "North American Product Classification System (NAPCS) Canada 2017 - Trade Variant",
        "targetVersionNumber": "1.0.0"
      },
      {
        "@id": "https://https://rdaas-statcan.dev.api.canada.ca/concordance/uO0FgUmO4zNwL0By",
        "name": "Mode of Transport - CBSA V1.0.0 to V2.0.0",
        "versionNumber": "1.0.0",
        "audience": "PUBLIC",
        "status": "RELEASED",
        "lastUpdated": "2021-04-09T21:15:17.000Z",
        "validFrom": null,
        "validTo": null,
        "source": "https://https://rdaas-statcan.dev.api.canada.ca/classification/DQ9p4Pyfu9g4gcnN",
        "source_name": "Mode of Transport - CBSA",
        "sourceVersionNumber": "1.0.0",
        "target": "https://https://rdaas-statcan.dev.api.canada.ca/classification/MAPNwNaJqcTbdOjz",
        "target_name": "Mode of Transport - CBSA",
        "targetVersionNumber": "2.0.0"
      }
    ]
  },
  "found": 967,
  "start": 0,
  "limit": 10,
  "facets": {
    "status": {
      "RETIRED": 948,
      "RELEASED": 19
    },
    "audience": {
      "PUBLIC": 967
    }
  }
}

Concordance search filters

This will return a list of filters and the values that can be used on them when searching for concordances. The can be used as query parameters on any search request. For example, if the there is a filter named "bank" with values "A", "B", and "C", query parameters can be added to any search request to filter the results based on these values. For instance, to filter on "bank" "A" and "B", one could append ?bank=A&bank=B to the query url. It is worth noting that these filers will also be included as facet counts in all search results.

Concordance search filters - more information

Get URL:
/search/concordances/filters

Parameters:
None

Response Code:
200- Search classifications.

Example:
This call will return the list of filters available to be used in other calls.

Call:
https://rdaas-statcan.dev.api.canada.ca:443/search/concordances/filters

Results:

[
  {
    "parameter": "status",
    "values": [
      "RELEASED",
      "RETIRED",
      "ARCHIVED"
    ]
  },
  {
    "parameter": "audience",
    "values": [
      "PUBLIC"
    ]
  }
]

Classifications-codesets

Generally a statistical classification is a way to group a set of related categories in a meaningful, systematic, and standard format. The statistical classification is usually exhaustive, has mutually exclusive and well-described categories, and has either a hierarchical or a flat structure. A statistical classification usually contains codes and descriptors.

This section contains requests that provide information about classifications, their levels and codes, and changes across versions. These resources are available themselves in several different views (typically detailed and summary) along with a few utilities that are designed to provide users with answers to specific questions they may have without requiring them to dig through all the information themselves.

Codes / Categories

Codes are an alphanumeric or numeric value that is associated with a Category. Codes are organized in a classification by levels. In a flat classification there will be a single level that contains all the codes. In a hierarchical classification codes that are stored on the higher levels will be broader while those stored on the lower levels will be more specific refinements of their parents.

Classification detail

Provides detailed information about the specified classification. This includes descriptive information about the classification, version information, levels, and all codes arranged in order and hierarchically (if applicable).

Classification detail - more information

Get URL:
/classification/{id}

Parameters:

Name: Description
id * string (path): Identifier of the classification.
lang string (query): The internationalization language tags to request content in specific language(s). These can be comma separated. For example, "lang=en, fr-ca" See /api/i18n/tags under InternationalizationController for more details about language support.
Example: en
method string (query): The internationalization serialization method to use. See /api/i18n/methods under InternationalizationController for more details about language support.
Available values: SINGLE, PROPERTY, ARRAY, CONTAINER
Example: SINGLE

Response Code:
200- Search classifications.

Example:
This call will return all information available for the gender classification (lQA3IRH1ER3KXwrJ).

Call:
https://rdaas-statcan.dev.api.canada.ca:443/classification/lQA3IRH1ER3KXwrJ

Results:

"@context": [
    "https://https://rdaas-statcan.dev.api.canada.ca/context/classification-detail",
    {
      "@language": "en"
    }
  ],
  "@id": "https://https://rdaas-statcan.dev.api.canada.ca/classification/lQA3IRH1ER3KXwrJ",
  "name": "Sex at birth",
  "audience": "Non-standardized",
  "status": "Released",
  "lastUpdated": "2022-04-04T16:00:00.415Z",
  "description": "This standard was approved as a departmental standard on October 1, 2021",
  "versionName": "V1.0.0",
  "validFrom": "2021-10-01T00:00:00-04:00",
  "levels": [
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/level-summary",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/level/XV0o7C1uTxhWxZI5",
      "levelDepth": 1,
      "name": "Sex Categories",
      "codeCount": 2
    }
  ],
  "codes": [
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/code-tree-simple",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/code/vobFEu0ZvMjIOxsH",
      "code": "1",
      "descriptor": "Male",
      "definition": "This category includes persons whose reported sex at birth is male."
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/code-tree-simple",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/code/cFJZgJBj8RFFpFJE",
      "code": "2",
      "descriptor": "Female",
      "definition": "This category includes persons whose reported sex at birth is female."
    }
  ]
}

Classification Categories

Returns all categories at all levels of the classification as a flat list. If the classification is hierarchical, the categories here will not be presented in their hierarchy.

Classification Categories - more information

Get URL:
/classification/{id}/categories

Parameters:

Name: Description
id * string (path): Identifier of the classification version.
lang string (query): The internationalization language tags to request content in specific language(s). These can be comma separated. For example, "lang=en, fr-ca" See /api/i18n/tags under InternationalizationController for more details about language support.
Example: en
method string (query): The internationalization serialization method to use. See /api/i18n/methods under InternationalizationController for more details about language support.
Available values: SINGLE, PROPERTY, ARRAY, CONTAINER
Example: SINGLE

Response Code:
200- Get categories. 404- classification not found.

Example:
This call will return the gender classification (lQA3IRH1ER3KXwrJ) categories available.

Call:
https://rdaas-statcan.dev.api.canada.ca:443/classification/lQA3IRH1ER3KXwrJ/categories

Results:

{
  "@context": [
    "https://https://rdaas-statcan.dev.api.canada.ca/context/code-summary",
    {
      "@language": "en"
    }
  ],
  "@graph": [
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/code/cFJZgJBj8RFFpFJE",
      "code": "2",
      "descriptor": "Female",
      "definition": "This category includes persons whose reported sex at birth is female.",
      "levelDepth": 1
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/code/vobFEu0ZvMjIOxsH",
      "code": "1",
      "descriptor": "Male",
      "definition": "This category includes persons whose reported sex at birth is male.",
      "levelDepth": 1
    }
  ]
}

Classification Categories detailed

Returns the most detailed categories of the classification. These are the categories without any sub-categories. In most hierarchical classifications, these will be the categories from the lowest level. However, in a ragged classification these categories may exist at any level.

Classification Categories detailed - more information

Get URL:
/classification/{id}/categories/detailed

Parameters

Name: Description
id * string (path): Identifier of the classification.
lang string (query): The internationalization language tags to request content in specific language(s). These can be comma separated. For example, "lang=en, fr-ca" See /api/i18n/tags under InternationalizationController for more details about language support.
Example: en
method string (query): The internationalization serialization method to use. See /api/i18n/methods under InternationalizationController for more details about language support.
Available values: SINGLE, PROPERTY, ARRAY, CONTAINER
Example: SINGLE

Response Code:
200- Get detailed catagories 404- classification not found.

Example:
This call will return the gender classification (lQA3IRH1ER3KXwrJ) categories details available.

Call:
https://rdaas-statcan.dev.api.canada.ca:443/classification/lQA3IRH1ER3KXwrJ/categories/detailed

Results:

{
  "@context": [
    "https://https://rdaas-statcan.dev.api.canada.ca/context/code-summary",
    {
      "@language": "en"
    }
  ],
  "@graph": [
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/code/cFJZgJBj8RFFpFJE",
      "code": "2",
      "descriptor": "Female",
      "definition": "This category includes persons whose reported sex at birth is female.",
      "levelDepth": 1
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/code/vobFEu0ZvMjIOxsH",
      "code": "1",
      "descriptor": "Male",
      "definition": "This category includes persons whose reported sex at birth is male.",
      "levelDepth": 1
    }
  ]
}

Concordances

A Concordance is a correspondence table the formally expressed the relationships between subsequent version of variants of Classifications. It can exists between two versions of the same Classification, or across two different Classifications The relationships show how the items of the target relate to the items of the source.

A Concordance holds the collection of Maps between Codes of the source and target Classification. Several different types of Maps exist, from simple one to one correspondences to complex many-to-many relationships, complex mappings primarily exists across different versions of a Classifications.

Map Types

Different types of changes or Maps exist. The following definitions describe the types of maps that are possible in Ariā:

Deletion (1:0) - an existing Code expires
Creation (0:1) - a new Code comes into existence
Combinations (N:1)
Merger: two or more Codes expires, while their denotations proceed in one emerging Code
Take-over: a Code expires, while its denotation proceeds as part of the denotation of another item, which continues its existence
Decomposition (1:N)
Breakdown: a Code expires, while its denotation is distributed over and proceeds in two or more emerging items
Split-off: an Code continues to exist, while part of its denotation moves to another (emerging) Code
Transfer (M:N)
Simple
- Code Change (1:0, 0:1) - A Code expires, while its denotation proceeds as the denotation of en emerging item
- Property Change (1:1) - The name or other properties of a Code changes, while its denotation remains the same
- No Change (1:1) - No change takes place

Concordance detail.

Provides detailed information about the specified concordance. This includes descriptive information about the concordance, version information, and its code maps.

Concordance detail - more information

Get URL:
/api/concordance/{id}

Parameters:

Name: Description
id * string (path): Identifier of the concordance.
lang string (query): The internationalization language tags to request content in specific language(s). These can be comma separated. For example, "lang=en, fr-ca" See /api/i18n/tags under InternationalizationController for more details about language support.
Example: en
method string (query): The internationalization serialization method to use. See /api/i18n/methods under InternationalizationController for more details about language support.
Available values: SINGLE, PROPERTY, ARRAY, CONTAINER
Example: SINGLE

Response Code:
200- get concordance detail. 404- concordance not found.

Example:
This call will return the concordance detail for Reference data standard on Canadian provinces and territories V2002.0.0 to V2002.0.1 (s9aLOlj8BB6DplVz).

Call:
https://rdaas-statcan.dev.api.canada.ca:443/concordance/s9aLOlj8BB6DplVz

Results:

{
  "@context": [
    "https://https://rdaas-statcan.dev.api.canada.ca/context/concordance-detail",
    {
      "@language": "en"
    }
  ],
  "@id": "https://https://rdaas-statcan.dev.api.canada.ca/concordance/s9aLOlj8BB6DplVz",
  "name": "Reference data standard on Canadian provinces and territories V2002.0.0 to V2002.0.1",
  "audience": "Non-standardized",
  "status": "Released",
  "lastUpdated": "2022-04-14T19:06:36.372Z",
  "versionName": "V1.0.0",
  "validFrom": "2003-04-01T00:00:00-05:00",
  "source": "https://https://rdaas-statcan.dev.api.canada.ca/classification/DHE3EVBVfiUdi7n1",
  "target": "https://https://rdaas-statcan.dev.api.canada.ca/classification/pElnW6jZSn77dSFd",
  "versionConcordance": true,
  "codeMaps": [
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/RZT2TRNA8mnuideL",
      "maptype": "No Change",
      "sourceCode": "MB",
      "sourceDescriptor": "Manitoba",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "MB",
      "targetDescriptor": "Manitoba",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/poioFhrbrr6yoTv5",
      "maptype": "No Change",
      "sourceCode": "QC",
      "sourceDescriptor": "Quebec",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "QC",
      "targetDescriptor": "Quebec",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/Vhv5c0y4RoagICjZ",
      "maptype": "No Change",
      "sourceCode": "SK",
      "sourceDescriptor": "Saskatchewan",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "SK",
      "targetDescriptor": "Saskatchewan",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/DuxUs08tODCdSZKU",
      "maptype": "No Change",
      "sourceCode": "NS",
      "sourceDescriptor": "Nova Scotia",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "NS",
      "targetDescriptor": "Nova Scotia",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/lBxOFiFMqryqblaq",
      "maptype": "No Change",
      "sourceCode": "NL",
      "sourceDescriptor": "Newfoundland and Labrador",
      "sourceSinceVersion": "2002.0.0",
      "targetCode": "NL",
      "targetDescriptor": "Newfoundland and Labrador",
      "targetSinceVersion": "2002.0.0"
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/R52XeJK2hJY0FvFb",
      "maptype": "No Change",
      "sourceCode": "PE",
      "sourceDescriptor": "Prince Edward Island",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "PE",
      "targetDescriptor": "Prince Edward Island",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/rczeSiD0Bi5LslOv",
      "maptype": "No Change",
      "sourceCode": "BC",
      "sourceDescriptor": "British Columbia",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "BC",
      "targetDescriptor": "British Columbia",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/xzQH64AQ3MO8yobP",
      "maptype": "No Change",
      "sourceCode": "NU",
      "sourceDescriptor": "Nunavut",
      "sourceSinceVersion": "1999.0.0",
      "targetCode": "NU",
      "targetDescriptor": "Nunavut",
      "targetSinceVersion": "1999.0.0"
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/KFytLKZ437SzR11p",
      "maptype": "No Change",
      "sourceCode": "NT",
      "sourceDescriptor": "Northwest Territories",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "NT",
      "targetDescriptor": "Northwest Territories",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/CVuFLE9Nm0krCZ98",
      "maptype": "Update",
      "sourceCode": "YT",
      "sourceDescriptor": "Yukon Territory",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "YT",
      "targetDescriptor": "Yukon",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/XBApMvSyym0DFrcU",
      "maptype": "No Change",
      "sourceCode": "AB",
      "sourceDescriptor": "Alberta",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "AB",
      "targetDescriptor": "Alberta",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/NBEufKEmXO4g4Adm",
      "maptype": "No Change",
      "sourceCode": "ON",
      "sourceDescriptor": "Ontario",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "ON",
      "targetDescriptor": "Ontario",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@context": [
        "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
        {
          "@language": "en"
        }
      ],
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/X8TSQiUFKEgvH4gJ",
      "maptype": "No Change",
      "sourceCode": "NB",
      "sourceDescriptor": "New Brunswick",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "NB",
      "targetDescriptor": "New Brunswick",
      "targetSinceVersion": "1990.0.0"
    }
  ]
}

Code maps.

Returns the code maps for the specified concordance. This will not provide any additional information about the concordance. If users desire the complete detail of the concordance they can call api/concordance/{id} or if they want summary information they can call api/concordance/{id}/summary.

Code maps - more information

Get URL:
/api/concordance/{id}/maps

Parameters:

Name: Description
id * string (path): Identifier of the concordance.
lang string (query): The internationalization language tags to request content in specific language(s). These can be comma separated. For example, "lang=en, fr-ca" See /api/i18n/tags under InternationalizationController for more details about language support.
Example: en
method string (query): The internationalization serialization method to use. See /api/i18n/methods under InternationalizationController for more details about language support.
Available values: SINGLE, PROPERTY, ARRAY, CONTAINER
Example: SINGLE

Response Code:
200- Get code maps 404- corcordance not found.

Example:
This call will return the concordance detail maps for Reference data standard on Canadian provinces and territories V2002.0.0 to V2002.0.1 (s9aLOlj8BB6DplVz).

Call:
https://rdaas-statcan.dev.api.canada.ca:443/concordance/s9aLOlj8BB6DplVz/maps

Results:

{
  "@context": [
    "https://https://rdaas-statcan.dev.api.canada.ca/context/codemap-detail",
    {
      "@language": "en"
    }
  ],
  "@graph": [
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/RZT2TRNA8mnuideL",
      "maptype": "No Change",
      "sourceCode": "MB",
      "sourceDescriptor": "Manitoba",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "MB",
      "targetDescriptor": "Manitoba",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/poioFhrbrr6yoTv5",
      "maptype": "No Change",
      "sourceCode": "QC",
      "sourceDescriptor": "Quebec",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "QC",
      "targetDescriptor": "Quebec",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/Vhv5c0y4RoagICjZ",
      "maptype": "No Change",
      "sourceCode": "SK",
      "sourceDescriptor": "Saskatchewan",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "SK",
      "targetDescriptor": "Saskatchewan",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/DuxUs08tODCdSZKU",
      "maptype": "No Change",
      "sourceCode": "NS",
      "sourceDescriptor": "Nova Scotia",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "NS",
      "targetDescriptor": "Nova Scotia",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/lBxOFiFMqryqblaq",
      "maptype": "No Change",
      "sourceCode": "NL",
      "sourceDescriptor": "Newfoundland and Labrador",
      "sourceSinceVersion": "2002.0.0",
      "targetCode": "NL",
      "targetDescriptor": "Newfoundland and Labrador",
      "targetSinceVersion": "2002.0.0"
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/R52XeJK2hJY0FvFb",
      "maptype": "No Change",
      "sourceCode": "PE",
      "sourceDescriptor": "Prince Edward Island",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "PE",
      "targetDescriptor": "Prince Edward Island",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/rczeSiD0Bi5LslOv",
      "maptype": "No Change",
      "sourceCode": "BC",
      "sourceDescriptor": "British Columbia",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "BC",
      "targetDescriptor": "British Columbia",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/xzQH64AQ3MO8yobP",
      "maptype": "No Change",
      "sourceCode": "NU",
      "sourceDescriptor": "Nunavut",
      "sourceSinceVersion": "1999.0.0",
      "targetCode": "NU",
      "targetDescriptor": "Nunavut",
      "targetSinceVersion": "1999.0.0"
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/KFytLKZ437SzR11p",
      "maptype": "No Change",
      "sourceCode": "NT",
      "sourceDescriptor": "Northwest Territories",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "NT",
      "targetDescriptor": "Northwest Territories",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/CVuFLE9Nm0krCZ98",
      "maptype": "Update",
      "sourceCode": "YT",
      "sourceDescriptor": "Yukon Territory",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "YT",
      "targetDescriptor": "Yukon",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/XBApMvSyym0DFrcU",
      "maptype": "No Change",
      "sourceCode": "AB",
      "sourceDescriptor": "Alberta",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "AB",
      "targetDescriptor": "Alberta",
      "targetSinceVersion": "1990.0.0"

    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/NBEufKEmXO4g4Adm",
      "maptype": "No Change",
      "sourceCode": "ON",
      "sourceDescriptor": "Ontario",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "ON",
      "targetDescriptor": "Ontario",
      "targetSinceVersion": "1990.0.0"
    },
    {
      "@id": "https://https://rdaas-statcan.dev.api.canada.ca/codemap/X8TSQiUFKEgvH4gJ",
      "maptype": "No Change",
      "sourceCode": "NB",
      "sourceDescriptor": "New Brunswick",
      "sourceSinceVersion": "1990.0.0",
      "targetCode": "NB",
      "targetDescriptor": "New Brunswick",
      "targetSinceVersion": "1990.0.0"
    }
  ]
}

Report a problem or mistake on this page

Date modified:: 2022-12-12

Language selection

WxT Language switcher

Search and menus

WxT Search form

Reference data as a Services (RDaaS) - API User Guide

Revision history

Purpose of Document

Summary

Access and availability

Technology

Definitions

Application Programming Interface (API) methods and examples:

Search

Search concordances

Classifications-codesets

Codes / Categories

Concordances

Map Types