API Implementation Guide

Documentation Versions

v1

v2


Changelog

View More

Updated

Introduction

Local Contexts is focused on increasing Indigenous involvement in data governance through the integration of Indigenous values into data systems. Local Contexts offers digital strategies for Indigenous communities, institutions, and researchers through the Traditional Knowledge (TK) & Biocultural (BC) Labels and Notices. Together they function as a practical mechanism to advance aspirations for Indigenous data sovereignty and Indigenous innovation.

What is an API?

A RESTful API (or application programming interface) allows two computers to communicate with each other over the internet. In order to gather the information from the Local Contexts Hub to publish on your site, a request needs to be made through the API. Once a request has been made, the API then sends the corresponding data to your site instantly.

Anyone can connect to the API, no matter their skill level. This guide will detail how the API can be used.

Why use the API?

The purpose of the Local Contexts (LC Hub) API is to fetch Labels and Notices associated with a particular Local Contexts Hub Project via a GET request.

A GET request is a method used to request information from the API. In other words, it is the requested information that you are GETting from the API.

API Documentation (main site): https://localcontextshub.org/api

API Documentation (sandbox site): https://sandbox.localcontextshub.org/api

Contact Support: support@localcontexts.org

The Labels communicate ongoing Indigenous relationships, obligations, and responsibilities to information and data as well as expectations for its future circulation. Their implementation through the API keeps communities connected to the data and encourages researchers and institutions to adopt the use of the Local Contexts Hub in their Projects as well.

Connecting to the API also allows for automatic updates to any changes made to Projects such as:

  • Labels being added to a Project (replacing Notices)
  • Changes to Label text
  • Additional Labels added or removed from a Project

Back to Top ↑

Getting Started

In order to connect to the API, the following items must be completed:

  • Create or join an Institution/Researcher/Community account on the Local Contexts Hub.
  • Create or be added as a contributor to a Project.
    • When creating a Project, you will be asked for Project details, contacts, and have the option to add metadata. Projects can have three visibility types: Public, Discoverable, and Private. If Projects are set to Private, they will not be accessible via the API.
  • After creating a Project, be sure to have the Project ID readily available as this is the easiest way to retrieve all the details about a Project via the API.
    • Your Local Contexts Project ID is generated automatically when you create a Project. You can find the Project ID on the “View Project” page. For an example, visit the “How to find a Project ID” section of our “Getting Started” page.
  • OPTIONAL: The Project is shared with a community. NOTE: This step is not needed to view/connect to the Project via the API.

In the diagram below, the icon indicates when a connection to the API can be made.

Once these steps have been completed, a Project is ready to be connected via the API.


Please don’t hesitate to reach out to us at support@localcontexts.org. We are here to answer any questions you may have.

Back to Top ↑

Connecting to the API

If you would like to test out the API, you can create a Project via the Hub Test Site and using the following API Test Root Path: https://sandbox.localcontextshub.org/api/.

To connect to the official Local Contexts site via the API, use the API Root Path: https://localcontextshub.org/api/.

Our API v2 is the default version as of February 10, 2025. For v1, visit our API Guide (v1) page.

All endpoints for both the test site and the live site are the same, the only difference is the URL for the root path.

An API key from your Hub account is needed to authenticate to v2 of the API. Once connected, be sure to follow the usage guidelines below to ensure the Notices and Labels are being displayed properly.

When displaying any Notices or Labels, please be sure to reference the Usage Guides to ensure that the Notices and Labels are being displayed properly.

Back to Top ↑

Using the API

When using the API to display the Notices and Labels, the following guidelines need to be followed:

Displaying Notices

  • The text, icons, and titles for the Notices cannot be changed.
  • The only changes that can be made to the descriptive text is replacing the placeholder “our institution” with the name of the institution displaying the Institution Notices.
  • The Notices are intended to be displayed prominently on public-facing institutional websites, on digital collections pages, and or in finding aids.
  • When displaying the Notices, the title, icon, and text must all be displayed.
  • The Notices should be applied at a metadata field level.

More detailed information about displaying the notices can be found in the Engagement and Disclosure Notices Usage and Style Guide.

Displaying Labels

While the Label Icon may be displayed in isolation (or with one or both Titles), both Titles and the Customized Description should always be easily accessible as well. This could include providing:

  • The icons for the Labels cannot be changed.
  • Pop up, hover tooltip, etc… to give additional information about the specific Label being used.
  • Link to a page within the site/project/platform with additional information about all Labels being used.
  • Labels should be displayed prominently on pages where they are used.
  • Labels should be incorporated into a rights management or similar field.
  • Wherever possible, all text should be Unicode (UTF) compliant to ensure accurate representation across systems.
  • Text formatting and styling (eg: header tags, bold, italic) may be used in the Translated Title and Customized Description.
  • All text should also be readable without any styling, to ensure it can be used in different environments. Additional media (eg: audio recordings) may be embedded in the Translated Title.

More detailed information about displaying the notices can be found in the  Traditional Knowledge/Biocultural Labels Usage and Style Guide.

Updating Notices and Labels

Any updates done in the Hub are updated through the API instantly and automatically. In order to update any external records connected to the API, regular updates should be scheduled or manually run periodically.

Hub Maintenance

Sometimes the Local Contexts Hub or the test site will go into Maintenance Mode. If you try to access either of these sites, including the API, and you see an error page with a code of 503: Service Unavailable, it means that our developers are working hard to fix known issues or update the Hub. Some maintenance is planned. See the Hub Service Schedule for the next scheduled maintenance times. 

The best times to schedule automatic PULLs from the API would be between 12:00am-4:00am Pacific Time.

Back to Top ↑