wikirate4py.API — Wikirate API wrapper

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

Company Methods

API.get_company(identifier) → Company

Retrieves a company based on the given identifier (name or numerical ID).

Parameters:

identifier (str or int) – The identifier for the Wikirate entity. Can be either: - A numerical ID (e.g., 12345) - A name identifier (e.g., “Example_Company”)

Returns:

The retrieved Company object.

Return type:

Company

Raises:

Wikirate4PyException – If the identifier is not a valid string or positive integer.

Example

```python company = get_company(“Adidas AG”) print(company.name)

company = get_company(12345) print(company.name) ```

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.

Return type:

List[CompanyItem]

API.add_company(name: str, headquarters: str, **kwargs) → Company

Create and return a new company with the given name and headquarters.

Parameters:

  • name (str) – The name of the company.

  • headquarters (str) – The region where the company’s headquarters is located.

  • kwargs (dict) – Optional parameters such as ‘open_supply_id’, ‘wikipedia’, ‘open_corporates_id’, ‘website’, ‘international_securities_identification_number’, ‘legal_entity_identifier’, ‘sec_central_index_key’, ‘uk_company_number’ and ‘australian_business_number’

Returns:

The created company object.

Return type:

Company

Raises:

Wikirate4PyException – If name or headquarters is not provided.

Metric Methods

API.get_metric(identifier=None, metric_name=None, metric_designer=None) → Metric

Retrieves a Wikirate Metric based on either the identifier or a combination of metric name and metric designer.

Parameters:

  • identifier (str or int, optional) – Identifier for the metric, which can be either a numerical ID or a name identifier.

  • metric_name (str, optional) – Name of the metric (required if identifier is not provided).

  • metric_designer (str, optional) – Name of the metric designer (required if identifier is not provided).

Returns:

The retrieved Metric object.

Return type:

Metric

Raises:

Wikirate4PyException – If neither identifier nor the combination of metric_name and metric_designer is provided.

Example

`python metric = get_metric(identifier=12345) metric_by_name = get_metric(metric_designer="Commons", metric_name="Address") `

API.get_metrics(identifier=None, **kwargs) → List[MetricItem]

Retrieves a list of Wikirate Metrics based on the specified criteria.

Parameters:

  • identifier (str or int, optional) – The identifier for a specific Wikirate entity (e.g., a project or collection of metrics).

  • offset (int, optional) – The (zero-based) offset of the first item in the collection to return. Defaults to 0.

  • limit (int, optional) – The maximum number of entries to return. Defaults to 20. If the value exceeds the maximum allowed, it will be capped.

  • Filters (Additional)

  • ------------------

  • bookmark (bool, optional) – Filter metrics that are bookmarked by the user.

  • topic (str or list of str, optional) – Filter metrics related to specific topic(s).

  • topic_framework (str or list of str, optional) – Filter metrics related to specific topic framework(s).

  • designer (str, optional) – Filter metrics designed by a specific user or organization.

  • published (bool, optional) – Filter metrics by their publication status.

  • metric_type (str, optional) – Filter metrics by their type (e.g., “Score”, “Research”).

  • value_type (str, optional) – Filter metrics by the type of values they store (e.g., “Number”, “Text”).

  • metric_keyword (str, optional) – Search for metrics containing a specific keyword.

  • research_policy (str, optional) – Filter metrics by their research policy.

  • dataset (str, optional) – Filter metrics associated with a specific dataset.

Returns:

A list of MetricItem objects that match the specified criteria.

Return type:

List[MetricItem]

Raises:

Wikirate4PyException – If the request fails or an invalid parameter is passed.

Example

```python metrics = get_metrics(topic=”Climate Change”, limit=10) for metric in metrics:

print(metric.name)

```

Answer Methods

API.get_answer(identifier) → Answer

Retrieves a metric answer based on its identifier.

Parameters:

identifier (str or int) – The identifier of the relationship metric answer. This can be: - A numeric ID (e.g., 12345) - An alphanumeric identifier (e.g., “Core+Country+Adidas AG+2019”)

Returns:

The retrieved Answer object.

Return type:

Answer

Raises:

Wikirate4PyException – If the identifier is not a valid string or positive integer.

Example

```python answer = get_answer(identifier=”Core+Country+Adidas AG+2019”) print(answer.value)

answer = get_answer(identifier=12345) print(answer.value) ```

API.get_answers(metric_name=None, metric_designer=None, identifier=None, **kwargs) → List[AnswerItem]

Retrieves a list of Wikirate Answers by entity. The entity can be a metric name/ID, dataset name/ID, company name/ID, or source name/ID.

Parameters:

  • metric_name (str, optional) – Name of the relationship metric.

  • metric_designer (str, optional) – Name of the relationship metric designer.

  • identifier (str or int, optional) – Wikirate numeric identifier or alphanumeric entity name (e.g., “Adidas_AG”).

  • offset (int, optional) – The (zero-based) offset of the first item in the collection to return. Defaults to 0.

  • limit (int, optional) – The maximum number of entries to return. Defaults to 20.

  • year (int, optional) – Filter answers by the answer year.

  • status (str, optional) – Filter by answer status: all, exists, known, unknown, or none (not researched).

  • company_group (str, optional) – Filter answers by companies in the specified company group.

  • country (str, optional) – Filter answers by company location.

  • company (int, optional) – Wikirate company identifier to filter answers by a specific company.

  • company_identifier (str, optional) – Filter answers by global company identifiers such as ISIN, LEI, or OpenCorporates ID.

  • company_name (str, optional) – Filter answers by the full or partial company name.

  • metric_type (str, optional) – Filter by their metric type (e.g., “Score”, “Research”).

  • value_type (str, optional) – Filter answers by the value type of values they store (e.g., “Number”, “Text”).

  • research_policy (str, optional) – Filter answers by their metrics research policy.

  • dataset (str, optional) – Filter answers associated with a specific dataset.

  • topic (str or list of str, optional) – Filter answers related to specific topic(s).

  • topic_framework (str or list of str, optional) – Filter answers related to specific topic framework(s).

  • value (str or int, optional) – Match answers with the specified value.

  • value_from (int, optional) – Filter answers with a value greater than or equal to the specified value.

  • value_to (int, optional) – Filter answers with a value less than or equal to the specified value.

  • updated (str, optional) – Filter answers updated within a specific period (today, week, month).

  • updater (str, optional) –

    Filter answers updated by:

    • wikirate_team: Wikirate team

    • current_user: You

  • source (str, optional) – Filter answers by the specified source.

  • verification (str, optional) –

    Filter answers by verification level:

    • steward_added: Added by stewards

    • flagged: Flagged for verification

    • community_added: Added by community members

    • community_verified: Verified by community members

    • steward_verified: Verified by stewards

    • current_user: Verified by you

    • wikirate_team: Verified by Wikirate team

  • project (str, optional) – Filter answers associated with the specified Wikirate project.

  • bookmark (str, optional) –

    Filter answers by bookmark status:

    • bookmark: Answers you have bookmarked

    • nobookmark: Answers you have not bookmarked

  • sort_by (str, optional) – Sort answers by the specified field.

  • sort_dir (str, optional) – Direction of sorting (asc for ascending, desc for descending).

Returns:

A list of AnswerItem objects that match the specified criteria.

Return type:

List[AnswerItem]

Raises:

Wikirate4PyException – If an invalid parameter is passed or the request fails.

Example

```python answers = get_answers(metric_name=”Modern Slavery Statement”, metric_designer=”Business & Human Rights Resource Center”, year=2024, limit=10) for answer in answers:

print(answer.value)

```

API.add_answer(**kwargs) → Answer

Creates and returns an Answer object given the required parameters and optional ones.

Parameters:

  • metric_designer (str) – Name of the metric designer.

  • metric_name (str) – Name of the metric.

  • company (str or int) – The company to which the answer is assigned. Can be a company name (str) or ID (int).

  • year (int) – The reporting year.

  • value – The value of the answer.

  • source – The name of the source.

  • comment (str, optional) – A comment on the imported metric answer.

  • unpublished (optional) – Marks the answer as unpublished if set.

Returns:

The created answer object.

Return type:

Answer

Raises:

Wikirate4PyException – If any required parameter is missing.

API.update_answer(**kwargs) → Answer

Updates and returns an existing metric answer.

Parameters:

  • identifier (str, optional) – Unique identifier for the answer.

  • metric_designer (str, optional) – Name of the metric designer (required if identifier is not provided).

  • metric_name (str, optional) – Name of the metric (required if identifier is not provided).

  • company (str or int, optional) – The company the answer is assigned to (required if identifier is not provided).

  • year (int, optional) – The reporting year (required if identifier is not provided).

  • value (str or list, optional) – New value for the answer.

  • source (str or list, optional) – New source name.

  • comment (str, optional) – New comment on the metric answer.

  • unpublished (str, optional) – Marks the answer as unpublished if set.

Returns:

The updated answer object.

Return type:

Answer

Raises:

Wikirate4PyException – If any required parameter is missing.

Relationship Answer Methods

API.get_relationship(identifier) → Relationship

Retrieves a relation metric answer based on its identifier.

Parameters:

identifier (str or int) – The identifier of the relationship. This can be: - A numeric ID (e.g., 12345) - An alphanumeric identifier (e.g., “Commons+Supplied By+Adidas AG+2023+Interloop Limited HDI”)

Returns:

The retrieved Relationship object.

Return type:

Relationship

Raises:

Wikirate4PyException – If the identifier is not a valid string or positive integer.

Example

```python relationship = get_relationship(identifier=”16084531”) print(relationship.value)

relationship = get_relationship(identifier=16084531) print(relationship.value) ```

API.get_relationships(metric_name=None, metric_designer=None, identifier=None, **kwargs) → List[RelationshipItem]

Retrieves a list of Wikirate Relationships based on the specified criteria.

Parameters:

  • metric_name (str, optional) – Name of the relationship metric.

  • metric_designer (str, optional) – Name of the relationship metric designer.

  • identifier (str or int, optional) – Numeric or alphanumeric identifier of an entity that can have relationships (e.g., relationship metrics, companies, datasets).

  • offset (int, optional) – The (zero-based) offset of the first item in the collection to return. Defaults to 0.

  • limit (int, optional) – The maximum number of entries to return. Defaults to 20.

  • year (int, optional) – Filter relationships by the answer year.

  • status (str, optional) – Filter relationships by status: all, exists, known, unknown, or none.

  • company_group (str, optional) – Filter relationships with subject companies belonging to the specified company group.

  • value (str or int, optional) – Match relationships with the specified answer value.

  • value_from (int, optional) – Filter relationships with a value greater than or equal to the specified value.

  • value_to (int, optional) – Filter relationships with a value less than or equal to the specified value.

  • updated (str, optional) – Filter relationships updated within a specific period (today, week, month).

  • updater (str, optional) –

    Filter relationships updated by:

    • wikirate_team: Updated by Wikirate team

    • current_user: Updated by you

  • source (str, optional) – Filter relationships citing the specified source.

  • verification (str, optional) –

    Filter relationships by verification level:

    • steward_added: Added by stewards

    • flagged: Flagged for verification

    • community_added: Added by community members (e.g., students, volunteers)

    • community_verified: Verified by community members

    • steward_verified: Verified by stewards

    • current_user: Verified by you

    • wikirate_team: Verified by Wikirate team

  • project (str, optional) – Filter relationships associated with the specified Wikirate project.

  • bookmark (str, optional) –

    Filter relationships by bookmark status:

    • bookmark: Relationships you have bookmarked

    • nobookmark: Relationships you have not bookmarked

  • published (str, optional) –

    Filter relationships by publication status:

    • true: Published relationships (default)

    • false: Unpublished relationships

    • all: All published and unpublished relationships

  • object_company_name (str, optional) – Filter relationships by the object company name.

  • subject_company_name (str, optional) – Filter relationships by the subject company name.

  • object_company_id (int, optional) – Filter relationships by the object company ID.

  • subject_company_id (int, optional) – Filter relationships by the subject company ID.

Returns:

A list of RelationshipItem objects that match the specified criteria.

Return type:

List[RelationshipItem]

Raises:

Wikirate4PyException – If the request fails or an invalid parameter is passed.

Example

```python relationships = get_relationships(metric_name=”Sustainability Score”, metric_designer=”Example Designer”, year=2024, limit=10) for relationship in relationships:

print(relationship.value)

```

API.add_relationship(**kwargs)

Adds and returns a relationship metric answer.

Parameters:

  • metric_designer (str) – Name of the metric designer (e.g., “Designer Name”).

  • metric_name (str) – Name of the metric (e.g., “Metric Name”).

  • subject_company (str or int) – Subject company name or ID. This represents the main company in the relationship.

  • object_company (str or int) – Object company name or ID. This represents the related company in the relationship.

  • year (int) – Reporting year (e.g., 2024).

  • value (str or list) – Value of the relationship metric answer. If multiple values, provide a list.

  • source (str or list) – Source name(s) for the metric answer. If multiple sources, provide a list.

  • comment (str, optional) – Comment or discussion related to the metric answer.

Returns:

The created Relationship object.

Return type:

Relationship

Raises:

Wikirate4PyException – If any required parameter is missing or has a None value.

Example

```python relationship = add_relationship(

metric_designer=”Example Designer”, metric_name=”Example Metric”, subject_company=”Company A”, object_company=”Company B”, year=2024, value=”Positive Impact”, source=”Example Source”, comment=”This is an optional comment”

)

API.update_relationship(**kwargs) → Relationship

Updates and returns an existing relationship metric answer.

Parameters:

  • identifier (str, optional) – Unique identifier for the answer.

  • metric_designer (str) – Name of the metric designer.

  • metric_name (str) – Name of the metric.

  • subject_company (str or int) – Subject company name or ID of the answer to be updated.

  • object_company (str or int) – Object company name or ID of the answer to be updated.

  • year (int) – Reporting year of the answer to be updated.

  • value (str or list, optional) – New value for the relationship metric answer.

  • source (str or list, optional) – New source name.

  • comment (str, optional) – New comment on the metric answer.

Returns:

The updated relationship object.

Return type:

Relationship

Raises:

Wikirate4PyException – If any required parameter is missing.

Example

```python updated_relationship = update_relationship(

metric_designer=”Designer Name”, metric_name=”Metric Name”, subject_company=”Company A”, object_company=”Company B”, year=2024, value=”Updated Value”, source=”Updated Source”, comment=”Updated comment”

)

Source methods

API.get_source(identifier) → Source

Retrieves a Wikirate Source based on the given identifier.

Parameters:

identifier (str or int) – The identifier for the Wikirate Source. It can be either: - A numerical ID (e.g., 12345) - A name identifier (e.g., “Example_Source”)

Returns:

The retrieved Source object.

Return type:

Source

Raises:

Wikirate4PyException – If the identifier is not a valid string or positive integer.

Example

```python source = get_source(identifier=”Example_Source”) print(source.title)

source_by_id = get_source(identifier=12345) print(source_by_id.title) ```

API.get_sources(**kwargs) → List[SourceItem]

Retrieves a list of Wikirate Sources based on the specified criteria.

Parameters:

  • offset (int, optional) – The (zero-based) offset of the first item in the collection to return. Defaults to 0.

  • limit (int, optional) – The maximum number of entries to return. Defaults to 20. If the value exceeds the maximum allowed, it will be capped.

  • company (str or int, optional) – Filter sources where the company name or the numerical identifier is matched fully.

  • year (int, optional) – Filter sources by the reporting year.

  • wikirate_title (str, optional) – Filter sources where their title matches fully or partially the given string.

  • report_type (str, optional) – Filter sources based on the report type (e.g., “Sustainability Report”).

  • topic (str, optional) – Filter sources by the given topic.

  • wikirate_link (str, optional) – Filter sources where their URL matches fully or partially the given string.

Returns:

A list of SourceItem objects that match the specified criteria.

Return type:

List[SourceItem]

Raises:

Wikirate4PyException – If the request fails or an invalid parameter is passed.

Example

```python sources = get_sources(limit=10, offset=0, company_name=”Example Company”, year=2024) for source in sources:

print(source.title)

```

API.add_source(**kwargs) → Source

Adds and returns a new source.

Parameters:

  • title (str) – Title of the source (required).

  • link (str, optional) – URL of the original source (required if file is not provided).

  • file (str, optional) – File path to the file you want to upload as a source (required if link is not provided).

  • company (str or int, optional) – Company associated with the source. If an integer, it is treated as the company ID.

  • report_type (str, optional) – Type of the report (e.g., “Sustainability Report”).

  • year (int, optional) – Reporting year.

Returns:

The created source object.

Return type:

Source

Raises:

Wikirate4PyException – If the required title parameter is missing. If neither link nor file is provided. If the provided file path does not exist.

Example

```python new_source = add_source(

title=”Sustainability Report 2024”, link=”https://example.com/report.pdf”, company=”Example Company”, report_type=”Annual Report”, year=2024

)

API.update_source(**kwargs) → Source

Updates and returns an existing source.

Parameters:

  • name (str) – The unique identifier or name of the source to update (required).

  • title (str, optional) – Updated title of the source.

  • company (str or int, optional) – Updated reporting company. If an integer, it’s treated as the company ID.

  • report_type (str, optional) – Updated report type (e.g., “Sustainability Report”).

  • year (int, optional) – Updated reporting year.

Returns:

The updated source object.

Return type:

Source

Raises:

Wikirate4PyException – If the required name parameter is missing.

Example

```python updated_source = update_source(

name=”Source-12345678”, title=”Updated Sustainability Report”, company=”Example Company”, report_type=”Annual Report”, year=2023

)

Search methods

API.search_by_name(entity_type, name, **kwargs)

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_type –

    allowed entity types:

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

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

Return type:

Topic

API.get_topics(*, offset, limit)

Returns a list of Wikirate Topics

Parameters:

  • identifier – entity identifier with Topic subcard (e.g. a specific metric or dataset)

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

Return type:

List[TopicItem]

Research Group Methods

API.get_research_group(identifier) → ResearchGroup

Retrieves a Wikirate Research Group based on the given identifier.

Parameters:

identifier (str or int) – The identifier for the Research Group. It can be either: - A numerical ID (e.g., 12345) - A name identifier (e.g., “Example Research Group”)

Returns:

The retrieved ResearchGroup object.

Return type:

ResearchGroup

Raises:

Wikirate4PyException – If the identifier is not a valid string or positive integer.

Example

```python group = get_research_group(identifier=”Example Research Group”) print(group.name)

group = get_research_group(identifier=12345) print(group.name) ```

API.get_research_groups(**kwargs) → List[ResearchGroupItem]

Retrieves a list of Wikirate Research Groups based on the specified criteria.

Parameters:

  • offset (int, optional) – The (zero-based) offset of the first item in the collection to return. Defaults to 0.

  • limit (int, optional) – The maximum number of entries to return. Defaults to 20. If the value exceeds the maximum allowed, it will be capped.

  • Filters (Additional)

  • ------------------

  • name (str, optional) – Filter research groups by their name.

Returns:

A list of ResearchGroupItem objects that match the specified criteria.

Return type:

List[ResearchGroupItem]

Raises:

Wikirate4PyException – If the request fails or an invalid parameter is passed.

Example

```python research_groups = get_research_groups(limit=10, offset=0, name=”Climate Change Group”) for group in research_groups:

print(group.name)

```

Company Group Methods

API.get_company_group(identifier) → CompanyGroup

Retrieves a Wikirate Company Group based on the given identifier.

Parameters:

identifier (str or int) – The identifier for the Company Group. It can be either: - A numerical ID (e.g., 12345) - A name identifier (e.g., “Example_Company_Group”)

Returns:

The retrieved CompanyGroup object.

Return type:

CompanyGroup

Raises:

Wikirate4PyException – If the identifier is not a valid string or positive integer.

Example

```python group = get_company_group(identifier=”Apparel 100”) print(group.name)

group = get_company_group(identifier=12345) print(group_by_id.name) ```

API.get_company_groups(**kwargs) → List[CompanyGroupItem]

Retrieves a list of Wikirate Company Groups based on the specified criteria.

Parameters:

  • offset (int, optional) – The (zero-based) offset of the first item in the collection to return. Defaults to 0.

  • limit (int, optional) – The maximum number of entries to return. Defaults to 20. If the value exceeds the maximum allowed, it will be capped.

  • Filters (Additional)

  • ------------------

  • name (str, optional) – Filter company groups by their name.

Returns:

A list of CompanyGroupItem objects that match the specified criteria.

Return type:

List[CompanyGroupItem]

Raises:

Wikirate4PyException – If the request fails or an invalid parameter is passed.

Example

```python company_groups = get_company_groups(limit=10, offset=0, name=”Apparel”) for group in company_groups:

print(group.name)

```

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

Return type:

Project

API.get_projects(**kwargs)

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.

Return type:

List[ProjectItem]

Region Methods

API.get_region(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

Return type:

Project

API.get_regions(**kwargs)

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.

Return type:

List[Region]

Delete Methods

API.delete_wikirate_entity(identifier: int) → bool

Deletes a Wikirate entity based on the given numeric identifier.

Parameters:

id (int) – The numeric identifier of the Wikirate entity to be deleted.

Returns:

True if the entity was successfully deleted, otherwise False.

Return type:

bool

Raises:

Wikirate4PyException – If the provided id is not a valid integer.

Example

```python success = delete_wikirate_entity(12345) if success:

print(“Entity deleted successfully.”)

```