wikirate4ruby 1.0.0 → 2.0.1

data/examples/Get Metric.md

@@ -0,0 +1,32 @@
+## Get Metric
+
+_A Metric is a tool for measuring. On WikiRate, metrics are used to measure company performance, and they are a way of
+asking the same question of many companies. It consists of a question, an About section (which describes why this metric
+is important and how it is used), and a Methodology section (which describes how to research the answer)._
+
+_Some metric answers are researched, and their values and source citations are entered directly. Other answers are
+dynamically calculated from other answers. [Learn More](https://wikirate.org/About_Metrics)_
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+The `get_metric` method take as an input either the metric name or the metric's identifier.
+
+Each metric's name is composed by it's designer+title (eg. Core+Company Report Available).
+```ruby
+# get a metric by name, returns a Metric object
+metric = client.get_metric("Core+Company_Report_Available")
+puts metric.question
+puts metric.about
+puts metric.methodology
+# prints the metric type
+puts metric.metric_type
+# print the formula applied for the calculations if the metric is a Formula metric 
+puts metric.formula
+# prints the metric as a json
+puts metric.to_json
+# prints the raw json response
+puts metric.raw_json
+# get a metric by id, returns a Metric object
+metric = client.get_metric(7217)
+```

data/examples/Get Metrics.md

@@ -0,0 +1,72 @@
+## Get Metrics
+
+_A Metric is a tool for measuring. On WikiRate, metrics are used to measure company performance, and they are a way of
+asking the same question of many companies. It consists of a question, an About section (which describes why this metric
+is important and how it is used), and a Methodology section (which describes how to research the answer)._
+
+_Some metric answers are researched, and their values and source citations are entered directly. Other answers are
+dynamically calculated from other answers. [Learn More](https://wikirate.org/About_Metrics)_
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+The `get_metrics` method take as an input a `Hash` where the user can define the parameters of their request. More
+specifically, we could divide our params in two different types of parameters, the endpoint parameters and the filter
+parameters. The endpoint parameters help us to iterate through our query's results and the filter parameters allow us to
+restrict our results based on specific given input.
+<div style="font-family:'Source Code Pro'; font-size:14px; padding-left: 0.5em; padding-right: 0.5em;">
+endpoint params:
+
+- **_limit:_** default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the
+  maximum value will be used.
+- **_offset:_** default value 0, the (zero-based) offset of the first item in the collection to return
+
+filter params:
+
+- **_name:_**: returns all metrics that contain in their name the given string.
+- **_bookmark_**: returns the metrics you have bookmarked, allowed parameter values:
+
+    - 'bookmark'
+    - 'nobookmark'
+- **_wikirate_topic_**: returns all metrics that fall under the defined wikirate topic. All wikirate topics can be
+  found [here](https://wikirate.org/Topic).
+- **_designer_**: returns all metrics the given designer created.
+- **_published_**: returns all metrics based on status published or not published. Note that only stewards are allowed
+  to filter based on status. Allowed parameter values:
+
+    - 'true': for published metrics (default)
+    - 'false': for not published metrics
+    - 'all': for published and unpublished
+- **_metric_type_**: returns all metrics of the given metric type. If you want to learn more about the different
+  wikirate metric types follow this [link](https://wikirate.org/About_Metrics). Allowed parameter values:
+
+    - 'researched'
+    - 'relationship'
+    - 'inverse relationship'
+    - 'formula'
+    - 'wikirating'
+    - 'score'
+    - 'descendant'
+- **_value_type_**: returns all metric that their answers are of the specified value type. Allowed parameter values:
+
+    - 'number'
+    - 'money'
+    - 'category'
+    - 'multi-category'
+    - 'free text'
+- **_research_policy_**: returns all metrics that follow the given research policy. Allowed parameter values:
+
+    - 'community assessed'
+    - 'designer assessed'
+- **_dataset_**: returns all metrics contained on the given dataset. All available wikirate datasets can be
+  found [here](https://wikirate.org/Data%20Set).
+
+</div>
+
+In the example below, we are asking to get 50 community assessed metrics which are designed by Walk Free
+
+```ruby
+metrics = client.get_metrics({ 'limit' => 50,
+                               'research_policy' => 'community assessed',
+                               'designer' => 'Walk Free' })
+```

data/examples/Get Project.md

@@ -0,0 +1,21 @@
+## Get Project
+
+_Projects are tools to organize, gather and analyse data on companies' environmental, social and governance performance.
+Through Projects you can pull together a specific set of companies (by topic or sector, for example) and metrics to help
+you and other WikiRate researchers contribute data that illuminates sustainability performance._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+The `get_project` method take as an input either the project name or the project's identifier.
+
+```ruby
+# get a project by name, returns a Card object
+project = client.get_project("Research: Business Contributions to the SDGs (PRME Research)")
+# prints the company as a json
+puts project.to_json
+# prints the raw json response
+puts project.raw_json
+# get a company by id, returns a Company object
+project = client.get_company(7927459)
+```

data/examples/Get Projects.md

@@ -0,0 +1,36 @@
+## Get Projects
+
+_Projects are tools to organize, gather and analyse data on companies' environmental, social and governance performance.
+Through Projects you can pull together a specific set of companies (by topic or sector, for example) and metrics to help
+you and other WikiRate researchers contribute data that illuminates sustainability performance._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+The `get_projects` method take as an input a `Hash` where the user can define the parameters of their request. More
+specifically, we could divide our params in two different types of parameters, the endpoint parameters and the filter
+parameters. The endpoint parameters help us to iterate through our query's results and the filter parameters allow us to
+restrict our results based on specific given input.
+<div style="font-family:'Source Code Pro'; font-size:14px; padding-left: 0.5em; padding-right: 0.5em;">
+endpoint params:
+
+- **_limit:_** default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the
+  maximum value will be used.
+- **_offset:_** default value 0, the (zero-based) offset of the first item in the collection to return
+
+filter params:
+
+- **_name:_** returns projects that contain in their name the given string
+- **_wikirate_status_**: returns projects of the given status. Allow parameter values:
+
+    - 'active'
+    - 'inactive'
+
+</div>
+
+In the example below, we are looking for all the currently active projects.
+
+```ruby
+projects = client.get_projects({ 'wikirate_status' => 'active' })
+puts projects
+```

data/examples/Get Relationship.md

@@ -0,0 +1,27 @@
+## Get Relationship
+
+_Wikirate platform can host answers that respond to relationship questions between companies. For instance, which
+companies supplied company A in 2022? Relationship answers respond to such questions (metrics with metric type
+Relation Metric)._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+The `get_relationship` method take as an input either the relationship answer's name or the relationship answer's
+identifier.
+
+Each relationship's name is described by the metric name (metric designer + metric title), subject company, year
+and object company.
+
+```ruby
+# get a relationship answer by name, returns a Relationship object
+answer = client.get_relationship("Commons+Tea Supplied By+Unilever+2021+Beitia Tea")
+# prints the relationship answer's value
+puts answer.value
+# prints the answer as a json
+puts answer.to_json
+# prints the raw json response
+puts answer.raw_json
+# get a relationship answer by id, returns an RelationshipAnswer object
+answer = client.get_relationship(8144117)
+```

data/examples/Get Relationships.md

@@ -0,0 +1,72 @@
+## Get Relationships
+
+_Wikirate platform can host answers that respond to relationship questions between companies. For instance, which
+companies supplied company A in 2022? Relationships respond to such questions (metrics with metric type
+Relation Metric)._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+The `get_relationships` method supports **multiple ways to identify the entity** whose relationships you want to retrieve:
+
+- by `metric_name` **and** `metric_designer`
+- by a generic `identifier` (numeric ID or card name)
+
+Additional request options are passed via the `params` hash.
+
+### Method signature
+
+```ruby
+get_answers(
+  metric_name: nil,
+  metric_designer: nil,
+  identifier: nil,
+  params: {}
+)
+```
+
+<div style="font-family:'Source Code Pro'; font-size:14px; padding-left: 0.5em; padding-right: 0.5em;">
+endpoint params:
+
+- **_limit:_** default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the
+  maximum value will be used.
+- **_offset:_** default value 0, the (zero-based) offset of the first item in the collection to return
+
+filter params:
+
+- **_year_**: returns all the relationships reported on the defined year
+- **_source_**: returns all relationships that cite the defined source
+- **_subject_company_id_**: returns all relationships by subject company id
+- **_object_company_id_**: returns all relationships by object company id
+- **_subject_company_name_**: returns all relationships by subject company name
+- **_object_company_name_**: returns all relationships by object company name
+- **_value_**: returns all the relationships with the defined value (e.g. Tier 2 Supplier)
+- **_name:_** returns all relationships with the subject company name containing the given string
+
+</div>
+
+In the example below, we are looking for Adidas AG suppliers in 2021.
+
+```ruby
+relationships = client.get_relationships('Supplied By',
+                                         'Commons',
+                                         { 'year' => 2021,
+                                           'name' => 'Adidas AG' })
+puts relationships
+```
+
+## Get Relationships by Metric ID
+
+The `get_relationships_by_metric_id` functions similarly with the `get_relationships` method but instead
+of `metric_name` and `metric_designer` gets as an input the `metric_id`.
+
+Thus, the examples equivalent examples of the previous section using the metric_id will be formulated as follows:
+
+In the example below, we are looking for Adidas AG suppliers in 2021.
+
+```ruby
+relationships = client.get_relationships(2929009,
+                                         { 'year' => 2021,
+                                           'name' => 'Adidas AG' })
+puts relationships
+```

data/examples/Get Research Group.md

@@ -0,0 +1,19 @@
+## Get Research Group
+
+_Research Groups are a collection of WikiRate contributors, their Research Projects, and Metrics they created._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+The `get_research_group` method take as an input either the research group's name or the research group's identifier.
+
+```ruby
+# get a research group by name, returns a ResearchGroup object
+research_group = client.get_research_group("University of Nottingham - Modern Slavery Research Group 2020")
+# prints the research group as a json
+puts research_group.to_json
+# prints the raw json response
+puts research_group.raw_json
+# get a research group by id, returns a ResearchGroup object
+research_group = client.get_research_group(2301582)
+```

data/examples/Get Research Groups.md

@@ -0,0 +1,30 @@
+## Get Research Groups
+
+_Research Groups are a collection of WikiRate contributors, their Research Projects, and Metrics they created._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+The `get_research_groups` method take as an input a `Hash` where the user can define the parameters of their request.
+More specifically, we could divide our params in two different types of parameters, the endpoint parameters and the
+filter parameters. The endpoint parameters help us to iterate through our query's results and the filter parameters
+allow us to restrict our results based on specific given input.
+<div style="font-family:'Source Code Pro'; font-size:14px; padding-left: 0.5em; padding-right: 0.5em;">
+endpoint params:
+
+- **_limit:_** default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the
+  maximum value will be used.
+- **_offset:_** default value 0, the (zero-based) offset of the first item in the collection to return
+
+filter params:
+
+- **_name:_** returns research groups that contain in their name the given string
+
+</div>
+
+In the example below, we are looking for research groups that contain in their name the string _University of Nottingham_.
+
+```ruby
+research_groups = client.get_research_groups({ 'name' => 'University of Nottingham' })
+puts research_groups
+```

data/examples/Get Source.md

@@ -0,0 +1,22 @@
+## Get Source
+
+_**All answers on WikiRate are sourced.** A source is generally a company report, including CSR Report, Sustainability Report, Annual Report or Integrated Report.
+It could also be a news article, website, conflict mineral report or modern slavery report and so on. A source can be
+added to WikiRate as a URL or file upload. Once a source is added it will remain on the platform so researchers can
+easily access the document._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+The `get_source` method take as an input either the source name or the source's identifier.
+
+```ruby
+# get a source by name, returns a Source object
+source = client.get_source("Source-000171202")
+# prints the source as a json
+puts source.to_json
+# prints the raw json response
+puts source.raw_json
+# get a source by id, returns a Source object
+source = client.get_source(13946225)
+```

data/examples/Get Sources.md

@@ -0,0 +1,68 @@
+## Get Sources
+
+_**All answers on WikiRate are sourced.** A source is generally a company report, including CSR Report, Sustainability
+Report, Annual Report or Integrated Report. It could also be a news article, website, conflict mineral report or modern
+slavery report and so on. A source can be added to WikiRate as a URL or file upload. Once a source is added it will
+remain on the platform so researchers can easily access the document._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+The `get_sources` method take as an input a `Hash` where the user can define the parameters of their request. More
+specifically, we could divide our params in two different types of parameters, the endpoint parameters and the filter
+parameters. The endpoint parameters help us to iterate through our query's results and the filter parameters allow us to
+restrict our results based on specific given input.
+<div style="font-family:'Source Code Pro'; font-size:14px; padding-left: 0.5em; padding-right: 0.5em;">
+endpoint params:
+
+- **_limit:_** default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the
+  maximum value will be used.
+- **_offset:_** default value 0, the (zero-based) offset of the first item in the collection to return
+
+filter params:
+
+- **_wikirate_title:_** returns sources that contain in their title the given string
+- **_wikirate_topic_**: returns sources that fall under the defined wikirate topic. All wikirate topics can be
+  found [here](https://wikirate.org/Topic).
+- **_year_**: returns sources that referred to the defined year.
+- **_wikirate_link_**: returns sources with where the source is linked to a url that contains the specified string
+- **_company_name_**: returns sources of companies that their name contain the given string.
+- **_report_type_**: returns all sources of the given report type. Allowed parameter values:
+
+    - 'Aggregate Data Report'
+    - 'Annual Report'
+    - 'Business Responsibility Report'
+    - 'Code of Conduct'
+    - 'Communication on Progress'
+    - 'Company Website'
+    - 'Conflict Minerals Report'
+    - 'Corporate Accountability Index'
+    - 'Corporate Social Responsibility Report'
+    - 'Data Breach Report'
+    - 'Gender Pay Gap Report'
+    - 'Human Rights Policy Document'
+    - 'Integrated Report'
+    - 'Member List'
+    - 'Modern Slavery Registry Submission'
+    - 'Modern Slavery Statement'
+    - 'Privacy Policy Document'
+    - 'Research Document'
+    - 'Responsible Investment Transparency Report'
+    - 'Signatory List'
+    - 'Standard'
+    - 'Supplier List'
+    - 'Supply Chain Policy document'
+    - 'Sustainability Report'
+    - 'Terms of Service'
+
+</div>
+
+In the example below, we are looking for Conflict Minerals Reports of Nike's for 2021 coming from the sec.gov.
+
+```ruby
+sources = client.get_sources({ 'company_name' => 'Nike Inc.',
+                               'wikirate_title' => 'Conflict Minerals',
+                               'wikirate_link' => 'sec.gov',
+                               'year' => 2021 })
+puts sources
+```

data/examples/Get Topic.md

@@ -0,0 +1,19 @@
+## Get Topic
+
+_Topics are a way to organize Metrics and other content into thematic groups._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+The `get_topic` method take as an input either the topic name or the topic's identifier.
+
+```ruby
+# get a topic by name, returns a Topic object
+topic = client.get_topic("Wikirate ESG Topics+Environment")
+# prints the topic as a json
+puts topic.to_json
+# prints the raw json response
+puts topic.raw_json
+# get a topic by id, returns a Topic object
+topic = client.get_topic(39152)
+```

data/examples/Get Topics.md

@@ -0,0 +1,47 @@
+## Get Topics
+
+_Topics are a way to organize Metrics and other content into thematic groups._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+The `get_topics` method take as an input a `Hash` where the user can define the parameters of their request. More
+specifically, we could divide our params in two different types of parameters, the endpoint parameters and the filter
+parameters. The endpoint parameters help us to iterate through our query's results and the filter parameters allow us to
+restrict our results based on specific given input.
+<div style="font-family:'Source Code Pro'; font-size:14px; padding-left: 0.5em; padding-right: 0.5em;">
+endpoint params:
+
+- **_limit:_** default value 20, the maximum number of entries to return. If the value exceeds the maximum, then the
+  maximum value will be used.
+- **_offset:_** default value 0, the (zero-based) offset of the first item in the collection to return
+
+filter params:
+
+- **_name:_** returns topics that contain in their name the given string
+- **_topic_framework:_** returns topics based on the defined Topic Framework, allowed paremeter values:
+
+  - `Wikirate ESG Topics`
+  - `ESRS Standards`
+  - `GRI Standards`
+  - `UN SDGs`
+- **_bookmark_**: returns the topics you have bookmarked, allowed parameter values:
+
+  - `bookmark`
+  - `nobookmark`
+
+</div>
+
+In the example below, we are looking for topics that contain on their name the string _environment_.
+
+```ruby
+topics = client.get_topics({ 'name' => 'environment' })
+puts topics
+```
+
+In the example below, we are looking for topics under the GRI Standards framework.
+
+```ruby
+topics = client.get_topics({ 'topic_framework' => 'GRI Standards' })
+puts topics
+```

data/examples/README.md

@@ -0,0 +1,36 @@
+Examples
+====================
+
+- [Configuration](Configuration.md#configuration)
+    - [API-Key](Configuration.md#api-key)
+    - [Authentication](Configuration.md#authentication)
+- [Get Company](Get%20Company.md#get-company)
+- [Get Companies](Get%20Companies.md#get-companies)
+- [Add Company](Add%20Company.md#add-company)
+- [Update Company](Update%20Company.md)
+- [Get Metric](Get%20Metric.md#get-metric)
+- [Get Metrics](Get%20Metrics.md#get-metrics)
+- [Get Source](Get%20Source.md#get-source)
+- [Get Sources](Get%20Sources.md#get-sources)
+- [Add Source](Add%20Source.md#add-source)
+- [Update Source](Update%20Source.md#update-source)
+- [Get Answer](Get%20Answer.md#get-answer)
+- [Get Answers](Get%20Answers.md#get-answers)
+- [Add Answer](Add%20Answer.md#add-answer)
+- [Update Answer](Update%20Answer.md)
+- [Get Answers by Metric ID](Get%20Answers.md#get-answers-by-metric-id)
+- [Get Relationship](Get%20Relationship.md#get-relationship)
+- [Get Relationships](Get%20Relationships.md#get-relationships)
+- [Get Relationships by Metric ID](Get%20Relationships.md#get-relationships-by-metric-id)
+- [Add Relationship](Add%20Relationship.md#add-relationship)
+- [Update Relationship](Update%20Relationship.md#update-relationship)
+- [Get Topic](Get%20Topic.md#get-topic)
+- [Get Topics](Get%20Topics.md#get-topics)
+- [Get Dataset](Get%20Dataset.md#get-dataset)
+- [Get Datasets](Get%20Datasets.md#get-datasets)
+- [Get Company Group](Get%20Company%20Group.md#get-company-group)
+- [Get Company Groups](Get%20Company%20Groups.md#get-company-groups)
+- [Get Research Group](Get%20Research%20Group.md#get-research-group)
+- [Get Research Groups](Get%20Research%20Groups.md#get-research-groups)
+- [Get Project](Get%20Project.md#get-project)
+- [Get Projects](Get%20Projects.md#get-projects)

data/examples/Update Answer.md

@@ -0,0 +1,47 @@
+## Update Answer
+
+_Wikirate platform helps users to find/research answers on specific questions/metrics about companies. Thus, each answer
+is described by the question/metric, company, value, year and source._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+WikiRate's REST API allows you to update existing answers. wikirate4ruby provides the
+method `update_research_metric_answer` to allow users to import answers on metrics. The method takes as an input a
+number of parameters where all the information about the existing answer is defined. The parameters can be split into
+required and optional.
+
+<div style="font-family:'Source Code Pro'; font-size:14px; padding-left: 0.5em; padding-right: 0.5em;">
+
+required params:
+
+- **_metric_designer_**: the designer of the metric we want to add the answer to
+- **_metric_name_**: the metric name/title of the metric we want to add the answer to
+- **_company_**: the company name/id the answer is referred to
+- **_year_**: the year the answer is referred to
+
+or
+
+- **_answer_id_**: the user can define directly the id of the answer, they want to update, instead of the aformentioned
+  paramaters
+
+optional params:
+
+- **_discussion_**: any comments we might have on the answer
+- **_value_**: the value/answer to the question
+- **_source_**: wikirate's source name of the source we found the answer
+
+</div>
+
+The example below demonstrates the update of an existing answer. Note that, if the answer does not exist if all the
+required parameters have been defined a new answer will be created (from the example below the source is missing for
+creating a new answer if that answer does not exist)
+
+```ruby
+updated_answer = client.update_answer({ 'metric_designer' => 'Walk Free',
+                                        'metric_name' => 'MSA Whistleblowing mechanism',
+                                        'company' => 'AIB Group plc',
+                                        'year' => 2017,
+                                        'value' => 'Supply Chain Workers' })
+```
+

data/examples/Update Company.md

@@ -0,0 +1,42 @@
+## Update Company
+
+_Any formal reporting organization (including corporations, NGOs, Universities, etc.) represented as a company on
+Wikirate._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+WikiRate's REST API allows you not only to create new companies but also to update existing ones. wikirate4ruby provides
+the method `update_company` to allow users updating existing companies. The method takes as an input a number of
+parameters on a `Hash` object and the users need to define the company and the fields they want to update.
+
+<div style="font-family:'Source Code Pro'; font-size:14px; padding-left: 0.5em; padding-right: 0.5em;">
+
+required params:
+
+- **_company:_** wikirate company name or identifier
+
+optional params:
+
+- **_headquarters:_** the region/country the headquarters of the company are located. All the available wikirate Regions
+  can be found [here](https://wikirate.org/Regions).
+- **_open_corporates_**: company's open corporates identifier
+- **_wikipedia_**: company's page name on wikipedia
+- **_sec_cik_**: company's central index key as assigned by US Securities and Exchange Commission (SEC)
+- **_os_id:_** company's open supply hub identifier
+
+</div>
+
+In the example below, we are updating Nike Inc. headquarters location.
+
+```ruby
+nike = client.add_company({ 'company' => 'Nike Inc.',
+                            'headquarters' => 'Oregon (United States)' })
+```
+
+Instead of the company name we can use the company's identifier when performing updates:
+
+```ruby
+nike = client.add_company({ 'company' => 5800,
+                            'headquarters' => 'Oregon (United States)' })
+```

data/examples/Update Relationship.md

@@ -0,0 +1,43 @@
+## Update Relationship
+
+_Wikirate platform can host answers that respond to relationship questions between companies. For instance, which
+companies supplied company A in 2022? Relationships respond to such questions (metrics with metric type
+Relation Metric)._
+
+This example assumes you have configured your Wikirate REST `client`. Instructions on how to configure a client can be
+found in [examples/Configurations.md](https://github.com/wikirate/wikirate4ruby/blob/main/examples/Configuration.md)
+
+WikiRate's REST API allows you to not only to import but also update existing relationships. wikirate4ruby provides the
+method `udpate_relationship` to facilitate this functionality. The method takes as an input a number of
+parameters where all the information about the existing relationship and updated fields is defined. The parameters can
+be split into required and optional.
+
+<div style="font-family:'Source Code Pro'; font-size:14px; padding-left: 0.5em; padding-right: 0.5em;">
+
+required params:
+
+- **_metric_designer_**: the designer of the metric
+- **_metric_name_**: the metric name/title of the metric
+- **_subject_company_**: the company name/id of the subject company
+- **_object_company_**: the company name/id of the object company
+- **_year_**: the year the relationship is referred to
+
+or
+
+- **_answer_id_**: the user can define directly the id of the relationship, they want to update, instead of all the
+  aformentioned paramaters
+
+optional params:
+
+- **_value_**: the value/answer to the question
+- **_source_**: wikirate's source name of the source we found the mentioned relationship
+- **_discussion_**: any comments we might have on the answer
+
+</div>
+
+The example below demonstrates the import of a relationship to the _Commons_ metric _Supplied By_
+
+```ruby
+updated_relationship = client.update_relationship({ 'answer_id' => 6228782,
+                                                    'year' => 2018 })
+```