diff --git a/docs/tutorials/01_api/01_api_download.ipynb b/docs/tutorials/01_api/01_api_download.ipynb index 6f60e174..d7ec7b1e 100644 --- a/docs/tutorials/01_api/01_api_download.ipynb +++ b/docs/tutorials/01_api/01_api_download.ipynb @@ -26,15 +26,19 @@ "\n", "## Requirements\n", "\n", + "- Python\n", "- Python packages:\n", - " - `requests`\n", + " - `requests` (See the packages [documentation](https://requests.readthedocs.io/en/latest/) for more help)\n", " - jupyter notebook, e.g. `notebook` or `jupyterlab`\n", " - `shapely` (only for geometry data conversion)\n", "- Skills:\n", - " - use python with jupyter notebooks\n", + " - use [python](https://wiki.python.org/moin/BeginnersGuide) with [jupyter notebooks](https://docs.jupyter.org/en/latest/)\n", + " - _some_ understanding of [JSON encoded data](https://www.w3schools.com/js/js_json_datatypes.asp)\n", + "- Internet: obviously, but also make sure your network settings allow https traffic from python\n", "\n", - "## Feedback \n", - "You can provide feedback on this tutorial here: https://github.com/OpenEnergyPlatform/academy/issues/233" + "## Feedback\n", + "\n", + "You can provide feedback on this tutorial in this [github issue](https://github.com/OpenEnergyPlatform/academy/issues/233)\n" ] }, { @@ -47,9 +51,19 @@ }, { "cell_type": "code", - "execution_count": 1, - "metadata": {}, - "outputs": [], + "execution_count": 7, + "metadata": { + "metadata": {} + }, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "you can see the table in your browser here: https://openenergyplatform.org/dataedit/view/model_draft/tutorial_example_table\n" + ] + } + ], "source": [ "# install required packages with: pip install requests\n", "# import required packages\n", @@ -62,7 +76,10 @@ "\n", "topic = \"model_draft\"\n", "table = \"tutorial_example_table\"\n", - "table_api_url = f\"https://openenergyplatform.org/api/v0/schema/{topic}/tables/{table}/\"" + "table_api_url = f\"https://openenergyplatform.org/api/v0/schema/{topic}/tables/{table}/\"\n", + "table_web_url = f\"https://openenergyplatform.org/dataedit/view/{topic}/{table}\"\n", + "\n", + "print(f\"you can see the table in your browser here: {table_web_url}\")" ] }, { @@ -78,7 +95,9 @@ { "cell_type": "code", "execution_count": 2, - "metadata": {}, + "metadata": { + "metadata": {} + }, "outputs": [ { "name": "stdout", @@ -139,7 +158,9 @@ { "cell_type": "code", "execution_count": 3, - "metadata": {}, + "metadata": { + "metadata": {} + }, "outputs": [], "source": [ "from shapely import wkb\n", @@ -164,13 +185,16 @@ "source": [ "## Download filtered data\n", "\n", - "requires execution of [setup](#setup)\n" + "- requires execution of [setup](#setup)\n", + "- read more about [query strings](https://en.wikipedia.org/wiki/Query_string)\n" ] }, { "cell_type": "code", "execution_count": 4, - "metadata": {}, + "metadata": { + "metadata": {} + }, "outputs": [ { "name": "stdout", @@ -191,11 +215,23 @@ ], "source": [ "# Add (multiple) where filters to the url\n", + "\n", + "\n", "filter = \"where=is_active=true&where=capacity_mw>10\"\n", + "\n", + "\n", "res = req.get(table_api_url + f\"rows/?{filter}\")\n", + "\n", + "\n", + "\n", "data = res.json()\n", "\n", + "\n", + "\n", "# show results in notebook\n", + "\n", + "\n", + "\n", "print(json.dumps(data, indent=4))" ] }, @@ -212,7 +248,9 @@ { "cell_type": "code", "execution_count": 5, - "metadata": {}, + "metadata": { + "metadata": {} + }, "outputs": [ { "name": "stdout", @@ -220,6 +258,16 @@ "text": [ "{\n", " \"id\": \"test_table\",\n", + " \"_comment\": {\n", + " \"null\": \"If not applicable use: null\",\n", + " \"todo\": \"If a value is not yet available, use: todo\",\n", + " \"dates\": \"Dates and time must follow the ISO8601 including time zone (YYYY-MM-DD or YYYY-MM-DDThh:mm:ss\\u00b1hh)\",\n", + " \"units\": \"Use a space between numbers and units (100 m)\",\n", + " \"review\": \"Following the OEP Data Review (https://github.com/OpenEnergyPlatform/data-preprocessing/blob/master/data-review/manual/review_manual.md)\",\n", + " \"licenses\": \"License name must follow the SPDX License List (https://spdx.org/licenses/)\",\n", + " \"metadata\": \"Metadata documentation and explanation (https://github.com/OpenEnergyPlatform/oemetadata)\",\n", + " \"languages\": \"Languages must follow the IETF (BCP47) format (en-GB, en-US, de-DE)\"\n", + " },\n", " \"keywords\": [\n", " \"energy\",\n", " \"installations\",\n", @@ -229,59 +277,49 @@ " {\n", " \"name\": \"test_table\",\n", " \"schema\": {\n", - " \"foreignKeys\": [],\n", " \"fields\": [\n", " {\n", " \"name\": \"id\",\n", - " \"description\": \"numerical id of this data point\",\n", - " \"type\": \"integer\"\n", + " \"type\": \"integer\",\n", + " \"description\": \"numerical id of this data point\"\n", " },\n", " {\n", " \"name\": \"name\",\n", - " \"description\": \"name of installation\",\n", - " \"type\": \"string\"\n", + " \"type\": \"string\",\n", + " \"description\": \"name of installation\"\n", " },\n", " {\n", " \"name\": \"is_active\",\n", - " \"description\": \"true/false if installation is active\",\n", - " \"type\": \"boolean\"\n", + " \"type\": \"boolean\",\n", + " \"description\": \"true/false if installation is active\"\n", " },\n", " {\n", " \"name\": \"capacity_mw\",\n", - " \"description\": \"installed capacity in MW\",\n", - " \"type\": \"number\"\n", + " \"type\": \"number\",\n", + " \"description\": \"installed capacity in MW\"\n", " },\n", " {\n", " \"name\": \"installation_datetime_utc\",\n", - " \"description\": \"date (and time) when installation was build\",\n", - " \"type\": \"string\"\n", + " \"type\": \"string\",\n", + " \"description\": \"date (and time) when installation was build\"\n", " },\n", " {\n", " \"name\": \"location\",\n", - " \"description\": \"point location of installation\",\n", - " \"type\": \"geojson\"\n", + " \"type\": \"geojson\",\n", + " \"description\": \"point location of installation\"\n", " }\n", - " ]\n", + " ],\n", + " \"foreignKeys\": []\n", " }\n", " }\n", " ],\n", " \"metaMetadata\": {\n", - " \"metadataVersion\": \"OEP-1.5.2\",\n", " \"metadataLicense\": {\n", " \"name\": \"CC0-1.0\",\n", - " \"title\": \"Creative Commons Zero v1.0 Universal\",\n", - " \"path\": \"https://creativecommons.org/publicdomain/zero/1.0/\"\n", - " }\n", - " },\n", - " \"_comment\": {\n", - " \"metadata\": \"Metadata documentation and explanation (https://github.com/OpenEnergyPlatform/oemetadata)\",\n", - " \"dates\": \"Dates and time must follow the ISO8601 including time zone (YYYY-MM-DD or YYYY-MM-DDThh:mm:ss\\u00b1hh)\",\n", - " \"units\": \"Use a space between numbers and units (100 m)\",\n", - " \"languages\": \"Languages must follow the IETF (BCP47) format (en-GB, en-US, de-DE)\",\n", - " \"licenses\": \"License name must follow the SPDX License List (https://spdx.org/licenses/)\",\n", - " \"review\": \"Following the OEP Data Review (https://github.com/OpenEnergyPlatform/data-preprocessing/blob/master/data-review/manual/review_manual.md)\",\n", - " \"null\": \"If not applicable use: null\",\n", - " \"todo\": \"If a value is not yet available, use: todo\"\n", + " \"path\": \"https://creativecommons.org/publicdomain/zero/1.0/\",\n", + " \"title\": \"Creative Commons Zero v1.0 Universal\"\n", + " },\n", + " \"metadataVersion\": \"OEP-1.5.2\"\n", " }\n", "}\n" ] diff --git a/docs/tutorials/01_api/02_api_upload.ipynb b/docs/tutorials/01_api/02_api_upload.ipynb index 175ec267..57b638de 100644 --- a/docs/tutorials/01_api/02_api_upload.ipynb +++ b/docs/tutorials/01_api/02_api_upload.ipynb @@ -27,29 +27,25 @@ "\n", "## Requirements\n", "\n", - "To execute the following code you will need to need to be a registered user on the OEP and\n", - "\n", "- have your OEP API token at hand. You find this in settings tab in your profile page. (If you don't have a token see [Things you only need to do once](https://openenergyplatform.github.io/academy/tutorials/99_other/beginners_guide/#1-things-you-only-need-to-do-once).)\n", - "\n", - "You will also need to have the following installed on your computer:\n", - "\n", "- Python\n", "- Python packages:\n", - "\n", - " - `requests`\n", + " - `requests` (See the packages [documentation](https://requests.readthedocs.io/en/latest/) for more help)\n", " - jupyter notebook, e.g. `notebook` or `jupyterlab`\n", " - `shapely` (only for geometry data conversion)\n", - "\n", - "- Ideally you exhibit the following skills:\n", - " - use python with jupyter notebooks\n" + "- Skills:\n", + " - use [python](https://wiki.python.org/moin/BeginnersGuide) with [jupyter notebooks](https://docs.jupyter.org/en/latest/)\n", + " - _some_ understanding of [JSON encoded data](https://www.w3schools.com/js/js_json_datatypes.asp)\n", + "- Internet: obviously, but also make sure your network settings allow https traffic from python\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## Feedack \n", - "You can provide feedback on this tutorial here: https://github.com/OpenEnergyPlatform/academy/issues/234" + "## Feedback\n", + "\n", + "You can provide feedback on this tutorial in this [github issue](https://github.com/OpenEnergyPlatform/academy/issues/233)\n" ] }, { @@ -65,13 +61,15 @@ { "cell_type": "code", "execution_count": 1, - "metadata": {}, + "metadata": { + "metadata": {} + }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - "https://openenergyplatform.org/api/v0/schema/sandbox/tables/tutorial_example_table_94169/\n" + "https://openenergyplatform.org/api/v0/schema/sandbox/tables/tutorial_example_table_61248/\n" ] } ], @@ -131,14 +129,16 @@ }, { "cell_type": "code", - "execution_count": 3, - "metadata": {}, + "execution_count": 10, + "metadata": { + "metadata": {} + }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ - "you can see the data on the platform here: https://openenergyplatform.org/dataedit/view/sandbox/tutorial_example_table_94169\n" + "you can see the data on the platform here: https://openenergyplatform.org/dataedit/view/sandbox/tutorial_example_table_61248\n" ] } ], @@ -152,7 +152,7 @@ " raise Exception(res.text)\n", "\n", "\n", - "# NOTE: in the sandbox,this link will currentlynot work:\n", + "# NOTE: in the sandbox, this link will not work:\n", "print(\n", " f\"you can see the data on the platform here: https://openenergyplatform.org/dataedit/view/{topic}/{table}\"\n", ")" @@ -173,7 +173,9 @@ { "cell_type": "code", "execution_count": 4, - "metadata": {}, + "metadata": { + "metadata": {} + }, "outputs": [ { "name": "stdout", @@ -252,7 +254,9 @@ { "cell_type": "code", "execution_count": 6, - "metadata": {}, + "metadata": { + "metadata": {} + }, "outputs": [ { "name": "stdout", @@ -308,7 +312,9 @@ { "cell_type": "code", "execution_count": 7, - "metadata": {}, + "metadata": { + "metadata": {} + }, "outputs": [ { "name": "stdout",