update Knowledge Graph docs

docs/knowledge-graph/analytics-api-guide.md → docs/knowledge-graph/analytics-api.md

@@ -1,10 +1,10 @@
 ---
-sidebar_position: 10
+sidebar_position: 30
 toc_min_heading_level: 2
 toc_max_heading_level: 5
 ---
 
-# Analytics API Guide
+# Analytics API
 
 ## Introduction
 
@@ -25,6 +25,27 @@ Using the Analytics API requires a WordLift Key. If you're unsure which one is t
 
 In order to connect the Google Search Console to your Knowledge Graph, a client needs to perform an interactive authentication and authorization process with Google by using a Web Browser.
 
+### Determine the Resource Id {#determine-the-resource-id}
+
+Each website or domain in Google Search Console has a resource ID. The resource ID is required to configure the Analytics API properly.
+
+To retrieve the resource ID open the [Google Search Console](https://search.google.com/search-console) and select the desired website or domain from the left:
+
+![Select Website or Domain](./images/google-search-console-select-website-or-domain.png)
+
+Then select the `resource_id` value:
+
+![Copy and paste the resource ID](./images/google-search-console-copy-paste-the-resource-id.png)
+
+The value is URL encoded, and it requires to be decoded. [DuckDuckGo](https://duckduckgo.com) provides a handy way to decode a URL:
+
+![URL decode the resource ID](./images/google-search-console-use-duckduckgo-to-urldecode-url.png)
+
+Take note of the decoded resource ID, it will be used later (in this example `https://example.org`):
+
+![Copy and paste the decoded resource ID](./images/google-search-console-use-duckduckgo-to-urldecode-url-copy-paste.png)
+
+
 ### Create an Authorization URI
 
 The process starts using a specially crafted URL. To get the URL use the "Build Authorization URI" API (replace `<key>` with your WordLift Key):
@@ -89,11 +110,18 @@ curl -X "POST" "https://api.wordlift.io/google-search-console/oauth2/auth-code-e
      -H 'Authorization: Key <key>' \
      -H 'Content-Type: application/json; charset=utf-8' \
      -d $'{
-  "code": "<authorization-code>"
+  "code": "<authorization-code>",
+  "google_search_console_resource_id": "<resource_id>"
 }'
 
 ```
 
+:::tip
+
+If you don't know the resource ID, see [how to determine the resource ID](#determine-the-resource-id).
+
+:::
+
 If successful, the access token will be stored in the platform and the API will return an empty JSON object:
 
 ```json
@@ -105,3 +133,53 @@ If successful, the access token will be stored in the platform and the API will
   "refresh_token": "<refresh-token>"
 }
 ```
+
+## Connect Botify
+
+Botify is also supported as an alternative to Google Search Console, [inquire with us](https://wordlift.io/contact-us/).
+
+:::note
+
+You can only connect one platform at a time.
+
+:::
+
+## Update the Account with the URL
+
+The last step before calling the Analytics import is to configure the website URL:
+
+```sh
+## Update Accounts
+curl -X "PUT" "https://api.wordlift.io/accounts?key=<key>&url=<url>&country=<country>&language=<language>" \
+     -H 'Authorization: Key <key>' \
+     -H 'Accept: application/json' \
+     -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8'
+```
+
+Set the following parameters:
+
+* `key`: is the WordLift key associated with the account
+* `url`: is the URL of the target website (in the example above `https://example.org`)
+* `country`, optional: the 2 letters country code, e.g. `US`
+* `language`, optional: the 2 letters langauge code, e.g. `EN`
+
+If successful the API will response with 200 and the following JSON:
+
+```json
+{
+  "datasetURI": "https://data.example.org/dataset/",
+  "packageType": "<your-package-type>"
+}
+```
+
+## Call the Analytics Import
+
+Calling the Analytics import is as simple as submitting the following request:
+
+```sh
+curl -X "POST" "https://api.wordlift.io/analytics-imports" \
+     -H 'Authorization: Key <key>' \
+     -H 'Content-Type: application/json'
+```
+
+Replace `<key>` with your WordLift key. The API will import the analytics data for all the URLs published in the Knowledge Graph.

docs/knowledge-graph/index.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 0
+---
+
+# Knowledge Graph
+
+The Knowledge Graph constitutes the basic representation of the Knowledge Domain for a website or an account.
+
+There are several way to populate data in a Knowledge Graph.
+
+In this section you can populate data using URLs by providing a `sitemap.xml` file or manually by using the [Sitemap Import API](./sitemap-import.md).
+
+Once the web pages have been imported it is possible to populate the Analytics data by using the [Analytics API](./analytics-api.md).

docs/knowledge-graph/sitemap-import.md

@@ -0,0 +1,81 @@
+---
+sidebar_position: 20
+toc_min_heading_level: 2
+toc_max_heading_level: 5
+---
+
+# Sitemap Import API
+
+It is possible to jumpstart a Knowledge Graph by importing the URLs from a simple sitemap.xml file (i.e. a sitemap with a list of URLs; sitemap.xml with references to other sitemap files isn't yet supported). It is also possible to specify a list of URLs.
+
+## Import
+
+You can import web pages by providing a `sitemap.xml`` file or a list of URLs.
+
+### Import URLs from a sitemap.xml file
+
+Call the Sitemap import API by specifying the `sitemap.xml` URL in the `sitemap_url` property:
+
+```sh
+curl -X "POST" "https://api.wordlift.io/sitemap-imports" \
+     -H 'Authorization: Key <key>' \
+     -H 'Content-Type: application/json; charset=utf-8' \
+     -d $'{
+  "sitemap_url": "https://example.org/sitemap.xml"
+}'
+```
+
+The response is of type [NDJSON](https://ndjson.org/). Each line is a valid JSON with the details about the imported web page.
+
+### Import URLs by providing them to the request
+
+Call the Sitemap import API by specifying a list of URLs `urls` property:
+
+```sh
+curl -X "POST" "https://api.wordlift.io/sitemap-imports" \
+     -H 'Authorization: Key <key>' \
+     -H 'Content-Type: application/json; charset=utf-8' \
+     -d $'{
+  "urls": [ 
+    "https://example.org/file1.html",
+    "https://example.org/file2.html",
+    "https://example.org/file3.html"
+  ]
+}'
+```
+
+The response is of type [NDJSON](https://ndjson.org/). Each line is a valid JSON with the details about the imported web page.
+
+## Import Analytics data
+
+To import Analytics data see the [Analytics API](./analytics-api.md)
+
+## Query the data
+
+Query the imported data by using the GraphQL endpoint. This is an example GraphQL query:
+
+```graphql
+query {
+  entities(
+    page: 0
+    rows: 1000
+  ) {
+    id: iri
+    headline: string(name: "schema:headline")
+    text: string(name: "schema:text")
+    types: refs(name: "rdf:type")
+    url: string(name: "schema:url")
+    seoKeywords: strings(name: "seovoc:seoKeywords")
+    topThreeMonthsKeywords: topN(
+      name: "seovoc:seoKeywords"
+      sort: { field: "seovoc:3MonthsImpressions", direction: DESC }
+      limit: 3
+    ) {
+      name: string(name: "seovoc:name")
+      impressions: int(name: "seovoc:3MonthsImpressions")
+      clicks: int(name: "seovoc:3MonthsClicks")
+    }
+    source: strings(name: "seovoc:source")
+  }
+}
+```

docusaurus.config.js

@@ -78,7 +78,7 @@ const config = {
             items: [
               {
                 label: "Knowledge Graph",
-                to: "knowledge-graph/analytics-api-guide",
+                to: "knowledge-graph",
               },
               {
                 label: "WordPress Plugin",

sidebars.js

@@ -56,6 +56,12 @@ const sidebars = {
     //   id: "additional-resources",
     // },
   ],
+  "knowledge-graph": [
+    {
+      type: "autogenerated",
+      dirName: "knowledge-graph", // '.' means the current docs folder
+    },
+  ],
   "wordpress-plugin": [
     {
       type: "autogenerated",