diff --git a/docs/knowledge-graph/analytics-api-guide.md b/docs/knowledge-graph/analytics-api.md similarity index 56% rename from docs/knowledge-graph/analytics-api-guide.md rename to docs/knowledge-graph/analytics-api.md index d366f5c..12cd8a7 100644 --- a/docs/knowledge-graph/analytics-api-guide.md +++ b/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 `` 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 ' \ -H 'Content-Type: application/json; charset=utf-8' \ -d $'{ - "code": "" + "code": "", + "google_search_console_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": "" } ``` + +## 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=&url=&country=&language=" \ + -H 'Authorization: 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": "" +} +``` + +## 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 ' \ + -H 'Content-Type: application/json' +``` + +Replace `` with your WordLift key. The API will import the analytics data for all the URLs published in the Knowledge Graph. \ No newline at end of file diff --git a/docs/knowledge-graph/images/google-search-console-copy-paste-the-resource-id.png b/docs/knowledge-graph/images/google-search-console-copy-paste-the-resource-id.png new file mode 100644 index 0000000..bbef6c1 Binary files /dev/null and b/docs/knowledge-graph/images/google-search-console-copy-paste-the-resource-id.png differ diff --git a/docs/knowledge-graph/images/google-search-console-select-website-or-domain.png b/docs/knowledge-graph/images/google-search-console-select-website-or-domain.png new file mode 100644 index 0000000..d9dd87c Binary files /dev/null and b/docs/knowledge-graph/images/google-search-console-select-website-or-domain.png differ diff --git a/docs/knowledge-graph/images/google-search-console-use-duckduckgo-to-urldecode-url-copy-paste.png b/docs/knowledge-graph/images/google-search-console-use-duckduckgo-to-urldecode-url-copy-paste.png new file mode 100644 index 0000000..4f9c54d Binary files /dev/null and b/docs/knowledge-graph/images/google-search-console-use-duckduckgo-to-urldecode-url-copy-paste.png differ diff --git a/docs/knowledge-graph/images/google-search-console-use-duckduckgo-to-urldecode-url.png b/docs/knowledge-graph/images/google-search-console-use-duckduckgo-to-urldecode-url.png new file mode 100644 index 0000000..905ee9d Binary files /dev/null and b/docs/knowledge-graph/images/google-search-console-use-duckduckgo-to-urldecode-url.png differ diff --git a/docs/knowledge-graph/index.md b/docs/knowledge-graph/index.md new file mode 100644 index 0000000..7137ccd --- /dev/null +++ b/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). \ No newline at end of file diff --git a/docs/knowledge-graph/sitemap-import.md b/docs/knowledge-graph/sitemap-import.md new file mode 100644 index 0000000..7b1b973 --- /dev/null +++ b/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 ' \ + -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 ' \ + -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") + } +} +``` diff --git a/docusaurus.config.js b/docusaurus.config.js index db8dfed..2710cb3 100644 --- a/docusaurus.config.js +++ b/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", diff --git a/sidebars.js b/sidebars.js index 6db7132..b7675b8 100644 --- a/sidebars.js +++ b/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",