Welcome to wikirate4py’s documentation!¶

Installation¶

The easiest way to install the latest version from PyPI is by using pip:

pip install wikirate4py

You can also use Git to clone the repository from GitHub to install the latest development version:

git clone https://github.com/wikirate/wikirate4py.git
cd wikirate4py
pip install .

Alternatively, install directly from the GitHub repository:

pip install git+https://github.com/wikirate/wikirate4py.git

Getting Started¶

Introduction¶

If you are new using wikirate4py, this is the place to begin. The main goal of this tutorial is to get you started with wikirate4py. We will not go into too much detail here but we will present some basics.

Hello wikirate4py¶

api = wikirate4py.API('you_api_token')

# requesting to get details about a specific WikiRate company based on name
# wikirate4py models the response into a Company object
company = api.get_company('Puma')

# print company's details
pprint(company.json())

# get the raw json response
pprint(company.raw_json())

# print company's aliases
for alias in company.aliases:
    print(alias)

This example will retrieve details of the given WikiRate company. wikirate4py models the response into a Company object and the above script print’s company’s details in json and then prints the raw json response. Finally, prints all company’s aliases.

API¶

The API class provides access to almost the entire WikiRate RESTful API methods. Each method can accept various parameters and return responses. For more information about these methods please refer to API Reference.

Models¶

When you invoke an API method most of the times, it returns back a wikirate4py model class instance. This contains the data from WikiRate which we then use inside the application. wikirate4py simplifies WikiRate’s response but you can access the raw json by calling the raw_json method. For example the following code returns to us a Metric model:

# Get the Metric object for Address metric with metric designer Clean Clothes Campaign
metric = api.get_metric(metric_name='Address', metric_designer='Clean Clothes Campaign')

Models contain the data simplified and some helper methods which we can then use:

print(metric.id)
print(metric.name)
print(metric.designer)
print(metric.question)
print(metric.value_type)
pprint(metric.json())
pprint(metric.raw_json())

# prints all available parameters of Metric model
print(metric.get_parameters())

Cursor Tutorial¶

This tutorial describes details on pagination with Cursor objects

Introduction¶

We use pagination a lot in WikiRate API development. Iterating through companies, metrics, answers, relationship answers, sources, topics, projects etc. In order to perform pagination, we must supply an offset and a limit parameters with each of our requests. This requires a lot of boiler plate code just to manage the pagination loop. To facilitate iteration and require less code, wikirate4py provides the Cursor object.

How to use¶

Cursor handles all the iteration/pagination work for us behind the scenes, thus our code can focus entirely on processing the results.

api = wikirate4py.API('you_api_token')

# create Cursor object that iterates the results (results per page = 100, default value = 20)
cursor = wikirate4py.Cursor(api.get_metrics)

while cursor.has_next():
    # next method returns a list of Metric objects
    results = cursor.next()
    # do something more to process your results

Passing parameters¶

What if you need to pass parameters to an API method that supports iteration?

api.get_answers(metric_name='Company Report Available',
                metric_designer='Core',
                country='United Kingdom',
                year=2019)

Since we pass Cursor the callable, we can not pass the parameters directly into the method. Instead we pass the parameters into the Cursor constructor method as demonstrated below:

api = wikirate4py.API('you_api_token')

# create Cursor object that iterates the results (results per page = 100, default value = 20)
cursor = wikirate4py.Cursor(api.get_answers,
                            metric_name='Company Report Available',
                            metric_designer='Core',
                            country='United Kingdom',
                            year=2019)
while cursor.has_next():
    # next method returns a list of Metric objects
    results = cursor.next()
    # do something more to process your results

Limits¶

By default, WikiRate allows 20 items per page, however users can request from WikiRate’s API to return more items in one go. If you would like to request more items in one go using the Cursor then you need to define an additional parameter called per_page.

cursor = wikirate4py.Cursor(api.get_metrics, per_page=50)

while cursor.has_next():
    # next method returns a list of Metric objects
    results = cursor.next()
    # do something more to process your results

Note that, wikirate4py allows max 100 items per page. If you define per_page>100 then the Cursor by default will set per_page=100.

`wikirate4py.API` — WikiRate API wrapper¶

class wikirate4py.API(oauth_token, wikirate_api_url='https://wikirate.org/', auth=())¶

Company Methods¶

API.get_company(identifier)¶

Returns a company based on the given identifier (name or number)

Parameters: identifier – two different identifiers are allowed for WikiRate entities, numerical identifiers or name identifiers
Returns
Return type: Company

API.get_companies(*, offset, limit)¶

Returns a list of WikiRate Companies

Parameters

offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.

Returns

Return type

List[CompanyItem]

API.add_company(name, headquarters, *, oar_id, open_corporates)¶

Creates and Returns a company given the company name and headquarters

Parameters

name – company name
headquarters – name of the region the headquarters of the company is located
wikipedia – company’s wikipedia page url
oar_id – company’s identifier on https://openapparel.org
open_corporates – company’s identifier on https://opencorporates.com/

Returns

Return type

Company

Metric Methods¶

API.get_metric(metric_name, metric_designer)¶

Returns a WikiRate Metric based on the given metric name and metric designer.

Parameters

identifier – two different identifiers are allowed for WikiRate entities, numerical identifiers or name identifiers
metric_name – name of metric
metric_designer – name of metric designer

Returns

Return type

Metric

API.get_metrics(*, offset, limit)¶

Returns a list of WikiRate Metrics

Parameters

offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.

Returns

Return type

List[MetricItem]

Answer Methods¶

API.get_answer(id)¶

Returns a metric answer given its numeric identifier.

Parameters: id – numeric identifier of the metric answer
Returns
Return type: Company

API.get_answers(metric_name, metric_designer, **kwargs)¶

get_answers(metric_name, metric_designer, *, company_name, company_id, offset, limit, year, status, company_group, country, value, value_from, value_to,: updated, updater, outliers, source, verification, project, bookmark)

Returns a list of WikiRate Answers

Parameters

metric_name – name of relationship metric
metric_designer – name of relationship metric designer
company_name – restrict the answers based on the given company
company_id – restrict the answers based on the given company
offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.
year – answer year
status – all, exists (researched), known, unknown, or none (not researched)
company_group – company group name, restricts to answers with companies belonging in the specified company group
country – country name, restricts to answers with companies located in the specified country
value – answer value to match
value_from – restricts to answers with value greater than equal the specified value
value_to – restricts to answers with value less than equal the specified value
updated – today, week (this week), month (this month)
updater –
- wikirate_team, restricts to answers updated by the WikiRate team
- current_user, restricts to answers updated by you
outliers – get either only answers considered as outliers or get answers after exclude the outliers
source – source name, restricts to answers citing the specified source
verification –
restricts to answers mapped to the defined verification level:
- steward_added: answers added by account with “steward” status
- flagged: answers which have been flagged by the Researcher adding the answer to request verification
- community_added: answers added by community members (e.g. students / volunteers)
- community_verified: answers verified by community members (e.g. students / volunteers)
- steward_verified: answers verified by account with “steward” status
- current_user: answers verified by you
- wikirate_team: answers verified by WikiRate team
project – project name, restrict to answers connected to the specified WikiRate project
bookmark –
- bookmark, restrict to answers you have bookmarked
- nobookmark, restrict to answers you have not bookmarked
published –
- true, returns only published answers (default mode)
- false, returns only unpublished answers
- all, returns all published and unpublished answers

Returns

Return type

List[AnswerItem]

API.add_research_metric_answer(metric_designer, metric_name, company, year, value, source, *, comment)¶

Creates and Returns a company given the company name and headquarters

Parameters

metric_name – name of metric
metric_designer – name of metric designer
company – company the answer is assigned to
year – reporting year
value – value of the answer
source – source name
comment – comment on the imported metric answer

Returns

Return type

Answer

API.update_research_metric_answer(metric_designer, metric_name, company, year, *, value, source, comment)¶

Updates and Returns an existing metric answer

Parameters

metric_name – name of metric
metric_designer – name of metric designer
company – company the answer is assigned to
year – reporting year
value – new value
source – new source name
comment – new comment on the metric answer

Returns

Return type

Answer

Relationship Answer Methods¶

API.get_relationship_answer(id)¶

Returns a relationship metric answer given its numeric identifier.

Parameters: id – numeric identifier of the relationship metric answer
Returns
Return type: RelationshipAnswer

API.get_relationship_answers(metric_name, metric_designer, *, offset, limit, year, status, company_group, country, value, value_from, value_to, updated, updater, outliers, source, verification, project, bookmark)¶

Returns a list of WikiRate Relationship Answers

Parameters

metric_name – name of relationship metric
metric_designer – name of relationship metric designer
offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.
year – answer year
status – all, exists (researched), known, unknown, or none (not researched)
company_group – company group name, restricts to relationship answers with subject companies belonging in the specified company group
country – country name, restricts to relationship answers with subject companies located in the specified country
value – answer value to match
value_from – restricts to relationship answers with value greater than equal the specified value
value_to – restricts to relationship answers with value less than equal the specified value
updated – today, week (this week), month (this month)
updater –
- wikirate_team, restricts to relationship answers updated by the WikiRate team
- current_user, restricts to relationship answers updated by you
outliers – get either only relationship answers considered as outliers or get answers after exclude the outliers
source – source name, restricts to answers citing the specified source
verification –
restricts to relationship answers mapped to the defined verification level:
- steward_added: relationship answers added by account with “steward” status
- flagged: relationship answers which have been flagged by the Researcher adding the answer to request verification
- community_added: relationship answers added by community members (e.g. students / volunteers)
- community_verified: relationship answers verified by community members (e.g. students / volunteers)
- steward_verified: relationship answers verified by account with “steward” status
- current_user: relationship answers verified by you
- wikirate_team: relationship answers verified by WikiRate team
project
project name, restrict to relationship answers connected to the specified WikiRate project

bookmark
- bookmark, restrict to relationship answers you have bookmarked
- nobookmark, restrict to relationship answers you have not bookmarked
published - true, returns only published answers (default mode) - false, returns only unpublished answers - all, returns all published and unpublished answers

returns

rtype

List[RelationshipAnswerItem]

API.get_relationship_answers_by_metric_id(metric_id, *, offset, limit, year, status, company_group, country, value, value_from, value_to, updated, updater, outliers, source, verification, project, bookmark)¶

Returns a list of WikiRate Relationship Answers

Parameters

id – numeric identifier of the relationship metric
offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.
year – answer year
status – all, exists (researched), known, unknown, or none (not researched)
company_group – company group name, restricts to relationship answers with subject companies belonging in the specified company group
country – country name, restricts to relationship answers with subject companies located in the specified country
value – answer value to match
value_from – restricts to relationship answers with value greater than equal the specified value
value_to – restricts to relationship answers with value less than equal the specified value
updated – today, week (this week), month (this month)
updater –
- wikirate_team, restricts to relationship answers updated by the WikiRate team
- current_user, restricts to relationship answers updated by you
outliers – get either only relationship answers considered as outliers or get answers after exclude the outliers
source – source name, restricts to answers citing the specified source
verification –
restricts to relationship answers mapped to the defined verification level:
- steward_added: relationship answers added by account with “steward” status
- flagged: relationship answers which have been flagged by the Researcher adding the answer to request verification
- community_added: relationship answers added by community members (e.g. students / volunteers)
- community_verified: relationship answers verified by community members (e.g. students / volunteers)
- steward_verified: relationship answers verified by account with “steward” status
- current_user: relationship answers verified by you
- wikirate_team: relationship answers verified by WikiRate team
project
project name, restrict to relationship answers connected to the specified WikiRate project

bookmark
- bookmark, restrict to relationship answers you have bookmarked
- nobookmark, restrict to relationship answers you have not bookmarked
published - true, returns only published answers (default mode) - false, returns only unpublished answers - all, returns all published and unpublished answers

returns

rtype

List[RelationshipAnswerItem]

API.add_relationship_metric_answer(metric_designer, metric_name, company, year, value, source, *, comment)¶

Adds and Returns a relationship metric answer

Parameters

metric_name – name of metric
metric_designer – name of metric designer
subject_company – subject company name of the updated answer
object_company – object company name of the updated answer
year – reporting year
value – value of the relationship metric answer
source – source name
comment – comment on the imported metric answer

Returns

Return type

RelationshipAnswer

API.update_relationship_metric_answer(metric_designer, metric_name, company, year, value, source)¶

Updates and Returns an existing relationship metric answer

Parameters

metric_name – name of metric
metric_designer – name of metric designer
subject_company – subject company name of the updated answer
object_company – object company name of the updated answer
year – reporting year
value – new value
source – new source name
comment – new comment on the metric answer

Returns

Return type

RelationshipAnswer

Source methods¶

API.get_source(identifier)¶

Returns a WikiRate Source based on the given identifier (name or number)

Parameters: identifier – two different identifiers are allowed for WikiRate entities, numerical identifiers or name identifiers
Returns
Return type: Source

API.get_sources(*, offset, limit)¶

Returns a list of WikiRate Sources

Parameters

offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.
company_name – filter sources where the company name matches fully or partially the given string
year – filter sources based on given year
wikirate_title – filter sources where their title match fully or partially the given string
report_type – filter sources based on the report type
wikirate_topic – filter sources based on given topic
wikirate_link – filter sources where their url matches fully or partially the given string

Returns

Return type

List[Source]

API.add_source(link, title, company, report_type, year)¶

Updates and Returns an existing relationship metric answer

Parameters

link – url of the original source
file – file path to the file you want to upload as a source
title – give a title on the source
company – comment on the imported metric answer
report_type – source name
year – reporting year
file – filepath on the file you want to upload

Returns

Return type

Source

API.update_source(name, title, company, report_type, year)¶

Updates and Returns an existing source

Parameters

name – source name
title – updated source title
company – updated reporting company
report_type – updated report type
year – updated reporting year

Returns

Return type

Source

Search methods¶

API.search_by_name(entity, name, *, offset, limit)¶

Searches for a Company or Metric or Topic or Company Group or Research Group or Project by a given name. If offset and limit are not defined it returns the first 20 search results.

Parameters

entity –
allowed entities:
- Company,
- Metric,
- Topic,
- CompanyGroup,
- ResearchGroup,
- Project
name – search term
offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.

Returns

- A List of CompanyItem, or
- A List of MetricItem, or
- A List of TopicItem, or
- A List of CompanyGroupItem, or
- A List of ResearchGroupItem, or
- A List of ProjectItem

API.search_source_by_url(url, *, offset, limit)¶

Searches for a WikiRare Source based on a given url. If offset and limit are not defined it returns the first 20 search results.

Parameters

url – as a search term
offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.

Returns

Return type

List[Source]

Topic Methods¶

API.get_topic(identifier)¶

Returns a WikiRate Topic based on the given identifier (name or number)

Parameters: identifier – two different identifiers are allowed for WikiRate entities, numerical identifiers or name identifiers
Returns
Return type: Topic

API.get_topics(*, offset, limit)¶

Returns a list of WikiRate Topics

Parameters

offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.

Returns

Return type

List[TopicItem]

Research Group Methods¶

API.get_research_group(identifier)¶

Returns a WikiRate Research Group based on the given identifier (name or number)

Parameters: identifier – two different identifiers are allowed for WikiRate entities, numerical identifiers or name identifiers
Returns
Return type: ResearchGroup

API.get_research_groups(*, offset, limit)¶

Returns a list of WikiRate Research Groups

Parameters

offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.

Returns

Return type

List[ResearchGroupItem]

Company Group Methods¶

API.get_company_group(identifier)¶

Returns a WikiRate Company Group based on the given identifier (name or number)

Parameters: identifier – two different identifiers are allowed for WikiRate entities, numerical identifiers or name identifiers
Returns
Return type: CompanyGroup

API.get_company_groups(*, offset, limit)¶

Returns a list of WikiRate Company Groups

Parameters

offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.

Returns

Return type

List[CompanyGroupItem]

Project Methods¶

API.get_project(identifier)¶

Returns a WikiRate Project based on the given identifier (name or number)

Parameters: identifier – two different identifiers are allowed for WikiRate entities, numerical identifiers or name identifiers
Returns
Return type: Project

API.get_projects(*, offset, limit)¶

Returns a list of WikiRate Projects

Parameters

offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.

Returns

Return type

List[ProjectItem]

Region Methods¶

API.get_region(identifier)¶

get_project(identifier) Returns a WikiRate Region based on the given identifier (name or number)

Parameters: identifier – two different identifiers are allowed for WikiRate entities, numerical identifiers or name identifiers
Returns
Return type: Project

API.get_regions(*, offset, limit)¶

Returns the list of all geographic regions we use in WikiRate platform

Parameters

offset – default value 0, the (zero-based) offset of the first item in the collection to return
limit – default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the maximum value will be used.

Returns

Return type

List[Region]

Delete Methods¶

API.delete_wikirate_entity(id)¶: Deletes a WikiRate entity based on the given numeric identifier

Code Snippets¶

Introduction¶

Here, you can find some code snippets to help you use wikirate4py successfully. Contributions enhancing this section are more than welcome!

Get Verified Metric Answers¶

# returns all answers of Company Report Available metric that were added by a steward
answers = api.get_answers(metric_name='Company Report Available',
                          metric_designer='Core',
                          verification='steward_added',
                          year=2019)

Get Relationship Metric Answers¶

# returns all supplier of relationships where the suppliers is located in the United Kingdom
answers = self.api.get_relationship_answers(metric_name='Supplier of',
                                            metric_designer='Commons',
                                            country='United Kingdom')

Add Company¶

company = self.api.add_company(name='A Company',
                               headquarters='United Kingdom',
                               oar_id='OAR_ID_123'
                               )

Delete Company¶

#delete a company given it's numerical identifier
self.api.delete_company(123)

Add Source¶

source = self.api.add_source(url='https://en.wikipedia.org/wiki/Target_Corporation',
                             title='wikipedia page of Target Corporation 2021',
                             company='Target',
                             comment='07/07/2021 This is a comment',
                             year=2020)

Update Source¶

source = self.api.update_source(name='Source-000106092',
                                    year=2021)

Add Researched Metric Answer¶

answer = self.api.add_research_metric_answer(metric_name='Company Report Available',
                                             metric_designer='Core',
                                             value='No',
                                             year=2021,
                                             source='Source_000104408s',
                                             company='BORA 2 LTD',
                                             comment='This is a test import of a metric answer')

Update Researched Metric Answer¶

answer = self.api.update_research_metric_answer(metric_name='Company Report Available',
                                                metric_designer='Core',
                                                year=2021,
                                                company='BORA 2 LTD',
                                                source='Source_000104408')

Add Relationship Metric Answer¶

relationship = self.api.add_relationship_metric_answer(metric_name='Supplied by',
                                                       metric_designer='Commons',
                                                       year=2021,
                                                       value='Tier 1 Supplier',
                                                       source='Source-000106091',
                                                       subject_company=7217,
                                                       object_company=7457810)

Update Relationship Metric Answer¶

relationship = self.api.update_relationship_metric_answer(metric_name='Supplied by',
                                                          metric_designer='Commons',
                                                          year=2021,
                                                          value='Tier 2 Supplier',
                                                          subject_company=7217,
                                                          object_company=7457810,
                                                          comment='This a relationship answer')

Contributing¶

Contributions are more welcome, and they are greatly appreciated! You can contribute in several different ways:

Report Bugs¶

Report bugs at https://github.com/wikirate/wikirate4py/issues.

If you are reporting a bug, please include:

Details about your setup that can be helpful in troubleshooting.
Detailed steps to reproduce the bug.

Fix Bugs¶

Look through the GitHub issues for bugs. Anything tagged with “bug” is open to be implemented by the WikiRate team but also to the community.

Implement Features¶

Look through the GitHub issues for features. Anything tagged with “feature” is open be implemented by the WikiRate team but also to the community.

Write Documentation¶

wikirate4py could always use more documentation, whether is part of official wikirate4py docs, in docstrings, or even on the web in blog posts or articles.

Submit Feedback¶

Your feedback is more than welcome and the best way to send feedback is to file an issue at https://github.com/wikirate/wikirate4py/issues.

If you would like to propose a feature:

please explain in details how it would work and
keep the scope as narrow as possible

Welcome to wikirate4py’s documentation!¶

Installation¶

Getting Started¶

Introduction¶

Hello wikirate4py¶

API¶

Models¶

Cursor Tutorial¶

Introduction¶

How to use¶

Passing parameters¶

Limits¶

wikirate4py.API — WikiRate API wrapper¶

Company Methods¶

Metric Methods¶

Answer Methods¶

Relationship Answer Methods¶

Source methods¶

Search methods¶

Topic Methods¶

Research Group Methods¶

Company Group Methods¶

Project Methods¶

Region Methods¶

Delete Methods¶

Code Snippets¶

Introduction¶

Get Verified Metric Answers¶

Get Relationship Metric Answers¶

Add Company¶

Delete Company¶

Add Source¶

Update Source¶

Add Researched Metric Answer¶

Update Researched Metric Answer¶

Add Relationship Metric Answer¶

Update Relationship Metric Answer¶

Contributing¶

Report Bugs¶

Fix Bugs¶

Implement Features¶

Write Documentation¶

Submit Feedback¶

Indices and tables¶

`wikirate4py.API` — WikiRate API wrapper¶