API Implementation Guide

Last Updated August 16, 2022

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/biocodellc/localcontexts_db/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

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.
  • 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.

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://anth-ja77-lc-dev-42d5.uc.r.appspot.com/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.

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 on the TK and BC Notice Usage and Style Guide and the Institution 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 on the TK and BC 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.

CONTENTS – ENDPOINTS

Endpoints (Elaboration)

OBJECTS/RESULTS

Variables

API Overview: A list of all possible endpoints for the Local Contexts Hub API.
api_documentation: Displays the URL for the API Documentation.
audiofile: The URL for an audio file for a Label. If an audio file was not added, then this field will be NULL.
bc_labels: An array with BC Label information for a project. If no BC Labels are added, this array will be empty.
community: The name of the Community that created a project or a Label.
count: The total number of projects returned from the project list results.
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. 
created_by: An array detailing who placed the Notice or Label on to the project.
date_added: The date a project was created in the Hub.
date_modified: The date a project was modified. If a project was never modified, the date will be the same as date_added.
default_text: The default text for Notices.
id: The id number of a researcher, institution, or user.
img_url: The URL for a Notice or Label PNG image.
institution: Information on the institution that placed the Notice. If Notice was not placed by an institution, this field will be NULL.
institution_name: The name of an institution.
label_text: The text for a Label.
label_type: The type of Label added to a project. See Label Type Values for more information.
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.
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.
name: The name of a Notice or Label.
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.
notice: An array with Notice information for a project. If no Notice is added, this array will be empty.
notice_type: The type of Notice added to a project. See Notice Type Values for more information.
open_to_collaborate_notice: Displays the path of the Open to Collaborate endpoint.
orcid: The URL for a researcher’s ORCiD.
page: Page number for the search results, starting with page 1. Add ?page={NUMBER} to the end of the path.
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.
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.
project_detail: Displays the path of the Projects Detail endpoint. NOTE: the path is the same for projects with Notices or Labels.
project_page: A URL link for a project view page.
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.
projects_by_institution_id: Displays the path of the Project by Institution endpoint.
projects_by_researcher_id: Displays the path of the Project by Researcher endpoint.
projects_by_user_id: Displays the path of the Project by User endpoint.
projects_list: Displays the URL (including the path) of the Projects List endpoint.
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.
researcher: Information on the researcher that placed the Notice. If Notice was not placed by a researcher, this field will be NULL.
results: An array of the project results.
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.
svg_url: The URL for a Notice or Label SVG image.
title: The title of a project.
tk_labels: An array with TK Label information for a project. If no TK Labels are added, this array will be empty.
translated_name: The translated name of a Label.
translated_text: The translated text of a Label.
translations: An array with information on translation(s) of a Label.
unique_id: The unique_id of a project.
updated: The date a Notice or Label was added/updated/removed from a project.
usage_guide_ci_notices: Displays the URL for the Usage Guide for Cultural Institution Notices.
usage_guide_labels: Displays the URL for the Usage Guide for BC and TK Labels.
usage_guide_notices: Displays the URL for the Usage Guide for TK/BC Notices.
user: The username of a researcher.

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