Use the API

Introduction

Welcome to Wikirate API guide! If you're here, you're probably aware that an API is an Application Programming Interface, or a way for one software application to talk to another. Wikirate’s architecture is built around a RESTful API. This makes it easy to access Wikirate’s environmental, social and governance (ESG) data through simple HTTP requests. The API uses JSON payloads, a lightweight data-interchange format that’s easy for humans and machines to read and write. 

Why Use the Wikirate REST API?

The REST API is your gateway to integrating Wikirate data into your applications, tools, and workflows. Built on REST principles and utilizing JSON payloads for data exchange, the API offers:

• Ease of integration: RESTful endpoints with standardized JSON responses ensure compatibility with most development environments.

• Comprehensive access: Retrieve millions of ESG data points on corporate sustainability performance.

• Scalability: Build tools, dashboards, and visualizations that leverage real-time data tailored to ongoing projects.

• Automation: Simplify repetitive tasks such as data aggregation, updates, and adding new data to the platform seamlessly.

Quick Start Guide

1. Obtain an API Key

• Sign up on Wikirate and generate your API key from your profile page under the “Accounts” tab. 

1. Authenticate: 

• Add your API key to your request, either as a query parameter (?api_key=YOUR_API_KEY) or using the X-API-Key header.

2. Make your First API Call:

• Example: GET https://wikirate.org/Companies?api_key=YOUR_API_KEY&format=json

• For more examples, refer to the "Key Endpoints and Usage Examples" section.

Who Should Use This Guide?

This guide is intended for anyone looking to utilize Wikirate's REST API to integrate, analyze, and contribute data seamlessly. Whether you're building applications, conducting in-depth research, or working in advocacy, the API has you covered. This guide is particularly useful for:

• Developers creating applications or tools that integrate sustainability data.

• Researchers requiring structured JSON data for advanced environmental, social, and governance (ESG) analysis.

• Civil Society Organizations uploading field-collected data or accessing additional datasets to support more intricate analyses and reporting.

• Volunteers contributing data from public domain datasets to the platform, leveraging automation to streamline their efforts and maximize impact.

How Is Wikirate's Data structured? 

Wikirate's API, like its underlying data structure, is a little unconventional. But if you understand why and how the structure is unusual, the API design will make sense. So let's start there.

First, Wikirate is, as its name implies, a wiki. It is built with an open-sourced wiki platform called Decko, which uses wiki-inspired building blocks called cards to create complex web systems. Pretty much everything you interact with on Wikirate is a card: Companies, Metrics, Answers, Projects, Dataset, Topics, etc. –– they're all cards. What's particularly unusual is that the substructures of these pages are cards, too. The logo of a company, the formula of a metric, the topic tags on a dataset... it's cards all the way down.

The embrace of this wiki card concept helps Wikirate live up to its values of transparency. Since everything is a card, and every card stored has a revertible revision history, the Wikirate platform is deeply transparent, and it exposes not just current data but also data histories to its API.

API Fundamentals (Cards, Marks, IDs)

Card Marks

The API docs make frequent references to marks. "Mark" is our general term for any of the ways for uniquely identifying cards.

Names

Every card on Wikirate, across all types, has a unique name. You cannot, for example, have a project and a company with the same name. This helps Wikirate adhere to an old wiki principle that you should be able to link to any content knowing only its name, and (as we will see) it also makes for very user-friendly urls. This, too, applies to nested cards, which are typically organized using structured names. For example, the logo on a company card is the name of the card plus "image".  Here, for example, is the "Apple Inc+image" card:

Apple Inc.+Image

history edit build

While the standard form of a card's name retains punctuation and capitalization, these things are stripped in the key that governs Wikirate's namespace.  So "Apple Inc", "apple inc", "APPLE INC", and "Apple@#$#$%INC" all refer to the same card (which has the default form of "Apple Inc.").

IDs

Every real card on Wikirate also has a unique numerical ID. These IDs are seldom seen in the UI but can easily be exposed by adding "/id" (or, for a text response, "/id.txt" or "/id.json") to a standard card url.

• wikirate.org/Apple_Inc/id.txt

• wikirate.org/Apple_Inc+image/id.txt

The above shows that Apple Inc, and Apple Inc+image are indeed two different cards with different ids.  Now that we have figured out their ids, we can use the id in place of the name in any request by preceding the id with a tilde, eg:

• wikirate.org/~1578

• wikirate.org/Apple_Inc

Those two links are functionally equivalent. But note that IDs are more permanent than names; if a card's name is edited, its ID remains the same. So a best practice for coders using the API is to use friendly variable names for companies (or metrics or datasets or company groups or whatever else) to hold IDs for use in API calls.

Wait, back up. What do you mean every "real" card has an id? Some cards aren't real??

Indeed, some patterned cards are virtual, meaning that they aren't actually stored in the database. Instead, they are dynamically constructed on the fly using rules. Here are some examples:

Examples of virtual cards on Wikirate

• The metric CDP+Scope_2_Emissions is tagged with the topic Climate Change. The real card that stores this connection is the +topic card on the metric card: CDP+Scope_2_Emissions+topic. (If you don't believe me, you can confirm that it's real using the id trick above). It's also possible to see all the metrics tagged with a given topic using +metric cards on topic cards, eg Climate Change+metric. But there's no need to store a duplicate copy of the tagging there; that information can be found with a simple search. So this card is a virtual card dynamically generated based on rules, and (as you can confirm) it has no id.

• The metric Commons+Company_Category is a (fairly complex) formula metric that generates tens of thousands of answers. Maintaining a revision history of all these answers would be extremely computationally expensive, not to mention silly, since they're all governed by one formula. However, each of these answers can still be accessed by name, eg Commons+Company Category+Adage Capital Management LP+2019

Codenames

You may sometimes encounter a third identifier, the "codename".  Most cards don't have these, only cards that are referred to directly in code. These permanent identifiers are more developer friendly than IDs, and unlike IDs they are constant across different Decko sites that share the same code. To use a codename in a request, preface it with a colon (:).

Compound marks

Advanced Features (Sorting, Filtering, Views) 

Since Wikirate's data is structured around a single namespace, so is its API. Whereas most APIs have different endpoints for different datatypes, all Wikirate data is in cards, so we focus on a single card endpoint with many formats and views.

Formats

Wikirate's API provides data views in HTML, JSON, CSV, TXT, and other formats. Because images are also cards, image formats like PNG, JPEG, and SVG follow the same patterns.  In all cases, you can use any one of the following three methods to specify the format:

1. via filename extension, eg  GET /cardname.json

2. via query variable, eg GET /cardname?format=json

3. via http access header, eg Accept: application/json

Views

For any card on Wikirate, it's possible to add ".json" to its name to see a default JSON view for that card, but there are also many other views available. In the "Card marks" section above, we demonstrated on very simple view: id. There are two ways to specify a view:

1. in the path as /CARD_MARK/VIEW, eg GET /Apple_Inc/id

2. in the query as /CARD_MARK?view=VIEW, eg GET Apple_Inc?view=id

Handy JSON views

The API docs list some views for different types, but these JSON views are implemented for all cards:

• nucleus - a card's marks, its type, and a default url

• atom - nucleus details plus a card's content, where applicable.

• molecule - atom details plus metadata and connections to closely related cards (this is the default json view)

(Each item links to the described view of the *logo card.)

Sorting and filtering

If you've explored Wikirate's UI, you've likely noticed the prominent sorting and filtering features. All of this functionality is available via the API. And in fact, one handy pattern when you're getting started with Wikirate's API is to being by using the UI, and then to click on the JSON export link below the results.

Specific sorting and filtering parameters are documented in the SwaggerHub docs.

 

API Error Codes and Troubleshooting

400: Bad Request – Ensure required parameters are correct.

401: Unauthorized – Verify your API key or token.

404: Not Found – Check the endpoint or resource identifier.

500: Internal Server Error – Retry or contact support.

 

Python, Java & Ruby API Wrappers

Pre-built API wrappers are available for Python, Java and Ruby thanks to NLnet’s support. Access them on GitHub:

• Java Wrapper: wikirate4j

• Python Wrapper: wikirate4py

• Ruby: wikirate4ruby

Wikirate Labs

Folks are building cooler and cooler things with Wikirate's API. At labs.wikirate.org we're gathering the best experiments and making them easy to explore, study, and extend.

---