Feature/nws api stub

nws.ipynb

@@ -0,0 +1,161 @@
+{
+  "nbformat": 4,
+  "nbformat_minor": 0,
+  "metadata": {
+    "colab": {
+      "provenance": [],
+      "authorship_tag": "ABX9TyP9h1JYyXGqgDUWkosdnJiY"
+    },
+    "kernelspec": {
+      "name": "python3",
+      "display_name": "Python 3"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "source": [
+        "# Rivulet (Weather): National Weather Service (NWS) API\n",
+        "_by Danny Zheng_"
+      ],
+      "metadata": {
+        "id": "uk5kKtkuGCMt"
+      }
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "## Purpose of this Notebook\n",
+        "\n",
+        "This notebook was developed as part of NSF Grant 2445609 to support accessing and processing public data for middle and high school classroom activities.It's written to be relatively accessible to beginners, but if you have not interacted with computational notebooks or Python before, you may find navigating this tool difficult. (Check out the Show Your Work project for a gentle introduction to computational notebooks for educators!)\n",
+        "\n",
+        "Our project is focused on supporting data analysis and mechanistic reasoning in science education. In other words, we want students to learn how data provides information about how scientific mechanisms work and how understanding scientific mechanisms can help them to explain and interpret patterns in data. This builds on a long history of research on complex systems and agent-based modeling, and more closely connects that work to current expansions of data analysis across subjects.\n",
+        "\n",
+        "This tool focuses on connecting to the National Weather Service (NWS) API to access public weather data. The goal is to gather meteorological data (such as precipitation, air temperature, etc.) that can be used to explain and interpret patterns in water quality data. This supports the project's focus on helping students learn how data provides information about *how scientific mechanisms work*."
+      ],
+      "metadata": {
+        "id": "nkK-3s4ZGd1o"
+      }
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "## Part I: Setup and Location\n",
+        "\n",
+        "The NWS API is public and does not require a secret key. We will define our imports and location in one place to streamline the process. The NWS API uses a latitude/longitude point to find weather data."
+      ],
+      "metadata": {
+        "id": "yts9RE19Gkvo"
+      }
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "metadata": {
+        "id": "UQqtHh3lFCFw"
+      },
+      "outputs": [],
+      "source": [
+        "# Install necessary libraries for the NWS API and mapping\n",
+        "!pip install requests folium\n",
+        "\n",
+        "# Import libraries\n",
+        "import requests\n",
+        "import pandas as pd\n",
+        "import folium #Used to map\n",
+        "\n",
+        "# The NWS API requires a User-Agent for identification, NOT a secret key.\n",
+        "# IMPORTANT: Replace the email below with your actual email.\n",
+        "USER_AGENT = \"(Rivulet Project, dazzy0130@gmail.com)\"\n",
+        "\n",
+        "# EDIT HERE: Define the target latitude and longitude for your region.\n",
+        "lat = 37.7749  # Example: San Francisco\n",
+        "lon = -122.4194"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "## Part I: Setup and Location\n",
+        "\n",
+        "The NWS API is public and does not require a secret key. We will define our imports and location in one place to streamline the process. The NWS API uses a latitude/longitude point to find weather data."
+      ],
+      "metadata": {
+        "id": "zMoFA9-WGpOT"
+      }
+    },
+    {
+      "cell_type": "code",
+      "source": [
+        "# Map the location\n",
+        "map_center = [lat, lon]\n",
+        "\n",
+        "# Create a Folium map object\n",
+        "m = folium.Map(location=map_center, zoom_start=12)\n",
+        "\n",
+        "# Add a marker to the map for the exact point\n",
+        "folium.Marker(\n",
+        "    location=[lat, lon],\n",
+        "    tooltip=\"Target NWS Location\"\n",
+        ").add_to(m)\n",
+        "\n",
+        "# Display the map\n",
+        "m"
+      ],
+      "metadata": {
+        "id": "-s2Trqs6FEx7"
+      },
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "source": [
+        "## Part III: Establishing the Connection\n",
+        "\n",
+        "This connection request is the foundational step. It retrieves the necessary metadata (the weather **grid ID** and **forecast URL**) that will be used for all subsequent weather data requests."
+      ],
+      "metadata": {
+        "id": "yeZunmhFGtPh"
+      }
+    },
+    {
+      "cell_type": "code",
+      "source": [
+        "# This API endpoint finds the correct weather grid for a given coordinate\n",
+        "api_endpoint = f\"https://api.weather.gov/points/{lat},{lon}\"\n",
+        "\n",
+        "# Set up the headers with our User-Agent (defined in Cell 6)\n",
+        "# Note: The NWS API requires this User-Agent header.\n",
+        "headers = {\n",
+        "    'User-Agent': USER_AGENT\n",
+        "}\n",
+        "\n",
+        "# 1. Make the request to the NWS API\n",
+        "response = requests.get(api_endpoint, headers=headers)\n",
+        "\n",
+        "# 2. Convert the successful JSON response into a Python dictionary\n",
+        "api_data = response.json()\n",
+        "\n",
+        "# The final output of the cell is the data dictionary, showing the key properties.\n",
+        "# Future steps will extract the URLs (like 'forecast') from this dictionary.\n",
+        "api_data['properties']"
+      ],
+      "metadata": {
+        "id": "Paht-fY4FR7y"
+      },
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "source": [],
+      "metadata": {
+        "id": "zsOy8aPiFTzx"
+      }
+    }
+  ]
+}