API Implementation Guide

Last Updated November 1, 2023

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: https://github.com/localcontexts/localcontextshub/wiki/API-Documentation

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/v1/.

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

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

No token is needed, just connect via either root path above to get started! 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 ↑

Endpoints

API Overview

Verb: GET
Path: /api/v1/
Description: Get a list of all possible endpoints
Response:
Content Type: application/json
Type: Object

Object Properties:

projects_list

Displays the URL (including the path) of the Projects List endpoint.
Type: string

project_detail

Displays the path of the Projects Detail endpoint. NOTE: the path is the same for Projects with Notices or Labels.
Type: string

multi_project_detail

Displays the path of the Multi-Project Detail endpoint. NOTE: this path will return Projects with BOTH Notices and Labels.
Type: string

projects_by_user_id

Displays the path of the Project by User endpoint.
Type: string

projects_by_institution_id

Displays the path of the Project by Institution endpoint.
Type: string

institution_projects_by_providers_id

Displays the path of the Institution Projects by Provider’s ID endpoint.
Type: string

projects_by_researcher_id

Displays the path of the Project by Researcher endpoint.
Type: string

open_to_collaborate_notice

Displays the path of the Open to Collaborate endpoint.
Type: string

api_documentation

Displays the URL for the API Documentation.
Type: string

usage_guides

Displays the URL to all Notices and Labels Usage Guides.
Type: string

Back to Top ↑

Project List

Verb: GET
Path: /api/v1/projects/
Description: Get a list of all Projects available through the Hub.

Querystring Parameters:
The following parameters can be added at the end of the path above for filtered/adjusted results.

page

Page number for the search results, starting with page 1. Add ?page={NUMBER} to the end of the path.
Type: int32

search

Filter out Projects by the unique_id, providers_id, or title. Note: The title does not have to be the full title, it can be a partial title. Add ?search={UNIQUE_ID or TITLE or PROVIDERS_ID} to the end of the path.
Type: string

Response:
Content Type: application/json
Type: Object

Object Properties:

count

The total number of Projects returned from the Project list results.
Type: int32

next

Displays the next page of the Project list results in URL form. If there is no following page, the data type will be NULL.
Type: string

previous

Displays the previous page of the Project list results in URL form. If there is no previous page, the data type will be NULL.
Type: string

results

An array of the Project results.
Type: array
Array Contents: see Project Results

Back to Top ↑

Project Detail (with Notices)

Verb: GET
Path: /api/v1/projects/{UNIQUE_ID}
Description: Loads the Project information of a Project with Notices by the Project’s unique_id.
Note: This will only show the Notice information if Labels are not yet applied to this Project.

Response:
Content Type: application/json
Type: Object

Object Properties:

unique_id

The unique_id of a Project or Label.
Type: string

providers_id

The provider_id for a Project (usually an external identifier separate from the unique_id in the Hub). If no provider id was added, then the data type will be NULL.
Type: string

source_project_uuid

The source_project_uuid for a Project (only applicable to Sub Projects). If this Project is not a Sub Project, then the data type will be NULL.
Type: string

project_page

A URL link for a Project view page.
Type: string

title

The title of a Project.
Type: string

project_privacy

The privacy setting set for a Project (either Public or Discoverable). If the privacy setting for a Project is set to Private in the Hub, it will not show in the API.
Type: string

date_added

The date a Project was created in the Hub.
Type: string

date_modified

The date a Project was modified. If a Project was never modified, the date will be the same as date_added.
Type: string

created_by

An array detailing who created a Project.
Type: Array
Array Contents: see Created By

notice

An array with Notice information for a Project. If no Notice is added, this array will be empty.
Type: Array
Array Contents: see Notice

sub_projects

An array with unique_ids for all Sub Projects connected to this Project. If no Sub Projects are connected, this array will be empty.
Type: Array

related_projects

An array with unique_ids for all Related Projects connected to this Project. If no Related Projects are connected, this array will be empty.
Type: Array

project_boundary_geojson

A GeoJSON array. GeoJSON is a format for encoding a variety of geographic data structures. If no information is available, this array will be empty.
Type: Array Contents: see GeoJSON

Back to Top ↑

Project Detail (with Labels)

Verb: GET
Path: /api/v1/projects/{UNIQUE_ID}
Description: Loads the Project information of a Project with Labels by the Project’s unique_id.
Note: This will only show the Label information if Labels are applied to this Project.

Response:
Content Type: application/json
Type: Object

Object Properties:

unique_id

The unique_id of a Project or Label.
Type: string

providers_id

The provider_id for a Project (usually an external identifier separate from the unique_id in the Hub). If no provider id was added, then the data type will be NULL.
Type: string

source_project_uuid

The source_project_uuid for a Project (only applicable to Sub Projects). If this Project is not a Sub Project, then the data type will be NULL.
Type: string

project_page

A URL link for a Project view page.
Type: string

title

The title of a Project.
Type: string

project_privacy

The privacy setting set for a Project (either Public or Discoverable). If the privacy setting for a Project is set to Private in the Hub, it will not show in the API.
Type: string

date_added

The date a Project was created in the Hub.
Type: string

date_modified

The date a Project was modified. If a Project was never modified, the date will be the same as date_added.
Type: string

created_by

An array detailing who created a Project.
Type: Array
Array Contents: see Created By

bc_labels

An array with BC Label information for a Project. If no BC Labels are added, this array will be empty.
Type: Array
Array Contents: see Label

tk_labels

An array with TK Label information for a Project. If no TK Labels are added, this array will be empty.
Type: Array
Array Contents: see Label

sub_projects

An array with unique_ids for all Sub Projects connected to this Project. If no Sub Projects are connected, this array will be empty.
Type: Array

related_projects

An array with unique_ids for all Related Projects connected to this Project. If no Related Projects are connected, this array will be empty.
Type: Array

project_boundary_geojson

A GeoJSON array. GeoJSON is a format for encoding a variety of geographic data structures. If no information is available, this array will be empty.
Type: Array Contents: see GeoJSON

Back to Top ↑

Multi-Project Detail

Verb: GET
Path: /api/v1/projects/multi/{UNIQUE_ID_1},{UNIQUE_ID_2},{UNIQUE_ID_3}
Description: Loads the Project information for all Projects whose unique_id is included at the end of the path.
NOTE: All unique_ids must be added with a comma separating each unique_id (no spaces).

Response:
Content Type: application/json
Type: Object

Object Properties:

notices_only

An array with Project details for each Project unique_id included in this call has Notices applied. If no information is available, this array will be empty.
Type: array
Array Contents: see Project Detail (with Notices)

labels_only

An array with Project details for each Project unique_id included in this call has Labels applied. If no information is available, this array will be empty.
Type: array
Array Contents: see Project Detail (with Labels)

no_labels_or_notices

An array with Project details for each Project unique_id included in this call has Labels applied. This will only occur if a Community creates a Project and has not yet applied Labels. If no information is available, this array will be empty.
Type: array
Array Contents: see Project Detail (with Labels)

Back to Top ↑

Project by User

Verb: GET
Path: /api/v1/projects/users/{ID}
Description: Get a list of all Projects of a user by the user’s id. If no Projects exist for this user, nothing will be returned.

Response:
Content Type: application/json
Type: Object

Object Properties:

unique_id

The unique_id of a Project or Label.
Type: string

providers_id

The provider_id for a Project (usually an external identifier separate from the unique_id in the Hub). If no provider id was added, then the data type will be NULL.
Type: string

title

The title of a Project.
Type: string

project_privacy

The privacy setting set for a Project (either Public or Discoverable). If the privacy setting for a Project is set to Private in the Hub, it will not show in the API.
Type: string

date_added

The date a Project was created in the Hub.
Type: string

date_modified

The date a Project was modified. If a Project was never modified, the date will be the same as date_added.
Type: string

Back to Top ↑

Project by Institution

Verb: GET
Path: /api/v1/projects/institutions/{ID}
Description: Get a list of all Projects of an institution by the institution’s id. If no Projects exist for this institution, nothing will be returned.

Response:
Content Type: application/json
Type: Object

Object Properties:

unique_id

The unique_id of a Project or Label.
Type: string

providers_id

The provider_id for a Project (usually an external identifier separate from the unique_id in the Hub). If no provider id was added, then the data type will be NULL.
Type: string

title

The title of a Project.
Type: string

project_privacy

The privacy setting set for a Project (either Public or Discoverable). If the privacy setting for a Project is set to Private in the Hub, it will not show in the API.
Type: string

date_added

The date a Project was created in the Hub.
Type: string

date_modified

The date a Project was modified. If a Project was never modified, the date will be the same as date_added.
Type: string

Back to Top ↑

Institution Projects by Providers ID

Verb: GET
Path: /api/v1/projects/institutions/{INSTITUTION_ID}/{PROVIDERS_ID}
Description: Get a list of all Projects of an institution by the institution’s id, filtered by a providers_id. If no Projects exist for this institution and provider’s ID, nothing will be returned.

Response:
Content Type: application/json
Type: Object

Object Properties:

unique_id

The unique_id of a Project or Label.
Type: string

providers_id

The provider_id for a Project (usually an external identifier separate from the unique_id in the Hub). If no provider id was added, then the data type will be NULL.
Type: string

title

The title of a Project.
Type: string

project_privacy

The privacy setting set for a Project (either Public or Discoverable). If the privacy setting for a Project is set to Private in the Hub, it will not show in the API.
Type: string

date_added

The date a Project was created in the Hub.
Type: string

date_modified

The date a Project was modified. If a Project was never modified, the date will be the same as date_added.
Type: string

Back to Top ↑

Project by Researcher

Verb: GET
Path: /api/v1/projects/researcher/{ID}
Description: Get a list of all Projects of a researcher by the researcher’s id. If no Projects exist for this researcher, nothing will be returned.

Response:
Content Type: application/json
Type: Object

Object Properties:

unique_id

The unique_id of a Project or Label.
Type: string

providers_id

The provider_id for a Project (usually an external identifier separate from the unique_id in the Hub). If no provider id was added, then the data type will be NULL.
Type: string

title

The title of a Project.
Type: string

project_privacy

The privacy setting set for a Project (either Public or Discoverable). If the privacy setting for a Project is set to Private in the Hub, it will not show in the API.
Type: string

date_added

The date a Project was created in the Hub.
Type: string

date_modified

The date a Project was modified. If a Project was never modified, the date will be the same as date_added.
Type: string

Back to Top ↑

Open to Collaborate

Verb: GET
Path: /api/v1/notices/open_to_collaborate
Description: Get information about the Open to Collaborate Notice.

Response:
Content Type: application/json
Type: Object

Object Properties:

notice_type

The type of Notice added to a Project.
Type: string

name

The name of a Notice or Label.
Type: string

default_text

The default text for Notices.
Type: string

img_url

The URL for the Notice PNG image.
Type: string

svg_url

The URL for the Notice SVG file.
Type: string

usage_guides

Displays the URL to all Notices and Labels Usage Guides.
Type: string

Back to Top ↑

Objects/Results

Project Results

Type: Object
Object Properties:

unique_id

The unique_id of a Project or Label.
Type: string

providers_id

The provider_id for a Project (usually an external identifier separate from the unique_id in the Hub). If no provider id was added, then the data type will be NULL.
Type: string

title

The title of a Project.
Type: string

project_privacy

The privacy setting set for a Project (either Public or Discoverable). If the privacy setting for a Project is set to Private in the Hub, it will not show in the API.
Type: string

date_added

The date a Project was created in the Hub.
Type: string

date_modified

The date a Project was modified. If a Project was never modified, the date will be the same as date_added.
Type: string

Back to Top ↑

Notice

Type: Object
Object Properties:

notice_type

The type of Notice added to a Project. See Notice Type Values for more information.
Type: string

name

The name of a Notice or Label.
Type: string

img_url

The URL for a Notice or Label PNG image.
Type: string

svg_url

The URL for a Notice or Label SVG file.
Type: string

default_text

The default text for Notices.
Type: string

translations

An array with information on translation(s) of a Notice or Label. If no information is available, this array will be empty.
Type: Array
Array Contents: see Translations

created

The date a Notice or Label was added to a Project. If previous Notice(s) or Label(s) are completely removed and replaced the created date will reflect when the new Notice(s) or Label(s) was placed.
Type: string

updated

The date a new Notice or Label was added/updated/removed from a Project.
Type: string

Back to Top ↑

Label

Type: Object
Object Properties:

unique_id

The unique ID of a Project or Label.
Type: string

name

The name of a Notice or Label.
Type: string

label_type

The type of Label added to a Project. See Label Type Values for more information.
Type: string

language_tag

The shortened indication of the language the text of a Label is written in. If left blank, this field will be a string with no characters in it.
Type: string

language

The full name of the language the text of a Label is written in. If left blank, this field will be a string with no characters in it.
Type: string

label_text

The text for a Label.
Type: string

img_url

The URL for a Notice or Label PNG image.
Type: string

svg_url

The URL for a Notice or Label SVG file.
Type: string

audiofile

The URL for an audio file for a Label. If an audio file was not added, then this field will be NULL.
Type: string

community

The name of the Community that created a Project or a Label.
Type: string

translations

An array with information on translation(s) of a Notice or Label. If no information is available, this array will be empty.
Type: Array
Array Contents: see Translations

created

updated

The date a new Notice or Label was added/updated/removed from a Project.
Type: string

Back to Top ↑

Created By

Type: Object
Object Properties:

institution

Information on the institution that placed the Notice. If Notice was not placed by an institution, this field will be NULL.
Type: Object (see Institution)

researcher

Information on the researcher that placed the Notice. If Notice was not placed by a researcher, this field will be NULL.
Type: Object (see Researcher)

community

The name of the Community that created a Project or a Label.
Type: string

Back to Top ↑

Researcher

Type: Object
Object Properties:

id

The id number of a researcher, institution, or user.
Type: int32

user

The username of a researcher.
Type: string

orcid

The URL for a researcher’s ORCiD.
Type: string

Back to Top ↑

Institution

Type: Object
Object Properties:

id

The id number of a researcher, institution, or user.
Type: int32

institution_name

The name of an institution.
Type: string

Back to Top ↑

Translations

Type: Object
Object Properties:

translated_name

The translated name of a Notice or Label.
Type: string

language_tag

The shortened indication of the language the text of a Notice or Label is written in. If left blank, this field will be a string with no characters in it.
Type: string

language

The full name of the language the text of a Notice or Label is written in. If left blank, this field will be a string with no characters in it.
Type: string

translated_text

The translated text of a Notice or Label.
Type: string

Back to Top ↑

Notice and Label Type Values

Notice Type Values:

traditional_knowledge
biocultural
attribution_incomplete
open_to_collaborate

Label Type Values:

TK Labels:

attribution
clan
family
outreach
tk_multiple_community
non_verified
verified
non_commercial
commercial
culturally_sensitive
community_voice
community_use_only
seasonal
women_general
men_general
men_restricted
women_restricted
secret_sacred
open_to_collaboration
creative

BC Labels:

provenance
commercialization
non_commercial
collaboration
consent_verified
consent_non_verified
multiple_community
research
clan
outreach

Back to Top ↑

Cookie	Duration	Description
cookielawinfo-checkbox-analytics	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Analytics".
cookielawinfo-checkbox-functional	11 months	The cookie is set by GDPR cookie consent to record the user consent for the cookies in the category "Functional".
cookielawinfo-checkbox-necessary	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookies is used to store the user consent for the cookies in the category "Necessary".
cookielawinfo-checkbox-others	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Other.
cookielawinfo-checkbox-performance	11 months	This cookie is set by GDPR Cookie Consent plugin. The cookie is used to store the user consent for the cookies in the category "Performance".
viewed_cookie_policy	11 months	The cookie is set by the GDPR Cookie Consent plugin and is used to store whether or not user has consented to the use of cookies. It does not store any personal data.

API Implementation Guide

On this Page

Introduction

What is an API?

Why use the API?

Getting Started

Connecting to the API

Using the API

Displaying Notices

Displaying Labels

Updating Notices and Labels

Hub Maintenance

Endpoints

API Overview

Project List

Project Detail (with Notices)

Project Detail (with Labels)

Multi-Project Detail

Project by User

Project by Institution

Institution Projects by Providers ID

Project by Researcher

Open to Collaborate

Objects/Results

Project Results

Notice

Label

Created By

Researcher

Institution

Translations

Notice and Label Type Values

Notice Type Values:

Label Type Values:

TK Labels:

BC Labels: