{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " # Assignment 1-2: Data Collection Using Web APIs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ## Objective"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " Many websites (such as Twitter, Yelp, Spotify) provide free APIs to allow users to access their data. In this assignment, you will learn the following:\n",
    "\n",
    "\n",
    "\n",
    " * How to ask insightful questions about data.\n",
    "\n",
    " * How to collect data from Web APIs using standard Python libraries.\n",
    "\n",
    "\n",
    "\n",
    " **Requirements:**\n",
    "\n",
    "\n",
    "\n",
    " 1. Use [pandas.DataFrame](http://pandas.pydata.org/pandas-docs/stable/generated/pandas.DataFrame.html) to manipulate data.\n",
    "\n",
    "\n",
    "\n",
    " 2. Follow the Python code style guide (https://www.python.org/dev/peps/pep-0008/). If your code is hard to read, you may lose points. This requirement will stay for the whole semester."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ## Preliminary"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " To complete this assignment, you will use Python libraries such as:\n",
    "\n",
    "\n",
    "\n",
    " - `requests` to make HTTP requests to the API.\n",
    "\n",
    " - `json` to parse JSON responses.\n",
    "\n",
    " - `pandas` to process and manipulate data.\n",
    "\n",
    "\n",
    "\n",
    " Before starting, you can refer to these tutorials:\n",
    "\n",
    "\n",
    "\n",
    " * [Python `requests` library](https://realpython.com/python-requests/)\n",
    "\n",
    " * [Working with JSON in Python](https://realpython.com/python-json/)\n",
    "\n",
    " * [Pandas basics](https://pandas.pydata.org/docs/user_guide/10min.html)\n",
    "\n",
    "## Finding APIs\n",
    "\n",
    "\n",
    "\n",
    " If you're unsure which API to explore, here are some useful resources:\n",
    "\n",
    " - [Public APIs GitHub Repository](https://github.com/public-apis/public-apis): A curated list of free APIs for development.\n",
    "\n",
    "\n",
    "\n",
    " Make sure the API you choose aligns with the assignment requirements and provides sufficient data to answer your questions."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ## Overview"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " This is a **group** assignment.\n",
    "\n",
    " Please check your group in this [Spreadsheet](https://1sfu-my.sharepoint.com/:x:/g/personal/sbergner_sfu_ca/EfiqKEqv4_pGgGjG0CvYBN4BvNM4FnJ-SvBAkIqVKN-iJA?e=LhVSqk).\n",
    "\n",
    "\n",
    "\n",
    " To complete this assignment, your group needs to go through the following steps:\n",
    "\n",
    "\n",
    "\n",
    " 1. Select a new Web API\n",
    "\n",
    " 2. Explore the API documentation to understand its capabilities and endpoints.\n",
    "\n",
    " 3. Formulate four questions that can be answered using the API.\n",
    "\n",
    " 4. Write Python code to query the API and answer these questions.\n",
    "\n",
    "\n",
    "\n",
    " ### Step 3: Formulating Questions\n",
    "\n",
    " Good questions should:\n",
    "\n",
    " - Be **useful**, answering common or novel data use cases.\n",
    "\n",
    " - Be **diverse**, covering various endpoints or use cases.\n",
    "\n",
    " - Have a range of **difficulty**, from simple (few parameters) to complex (multiple parameters or computations)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ### Example Questions (Yelp API)\n",
    "\n",
    "\n",
    "\n",
    " * Q1. What's the phone number of Capilano Suspension Bridge Park?\n",
    "\n",
    " * Q2. Which yoga store has the highest review count in Vancouver?\n",
    "\n",
    " * Q3. How many Starbucks stores are in Seattle and where are they located?\n",
    "\n",
    " * Q4. What are the ratings for a list of restaurants?\n",
    "\n",
    "\n",
    "\n",
    " These questions vary in usefulness, diversity, and complexity."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ## Now, it's your turn! :)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ### Instructions:\n",
    "\n",
    " 1. Choose an API and obtain access credentials (e.g., API key).\n",
    "\n",
    " 2. Write Python functions to query the API.\n",
    "\n",
    " 3. Answer each question using the API data.\n",
    "\n",
    " 4. Use `pandas` to format and display your results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "## Provide your API key here for TAs to reproduce your results\n",
    "API_KEY = \"your_api_key_here\"\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ### Q0: Write a function to fetch data from the API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "import pandas as pd\n",
    "\n",
    "def fetch_data(endpoint, params, headers=None):\n",
    "    \"\"\"\n",
    "    Fetch data from the given API endpoint with specified parameters.\n",
    "    \n",
    "    Args:\n",
    "        endpoint (str): The API endpoint URL.\n",
    "        params (dict): Dictionary of query parameters.\n",
    "        headers (dict): Optional headers for the request.\n",
    "\n",
    "    Returns:\n",
    "        dict: JSON response from the API.\n",
    "\n",
    "    Raises:\n",
    "        requests.exceptions.RequestException: If the request fails.\n",
    "    \"\"\"\n",
    "    try:\n",
    "        response = requests.get(endpoint, params=params, headers=headers, timeout=10)\n",
    "        response.raise_for_status()  # Raise an error for bad responses (4XX, 5XX)\n",
    "        return response.json()\n",
    "    except requests.exceptions.RequestException as e:\n",
    "        print(f\"An error occurred: {e}\")\n",
    "        return None\n",
    "\n",
    "# Example: Replace `example_api_endpoint` with your actual endpoint.\n",
    "# response = fetch_data(\"https://api.example.com/data\", {\"param1\": \"value1\"}, headers={\"Authorization\": f\"Bearer {API_KEY}\"})\n",
    "# print(response)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ### Q1: Retrieve business details for a specific place (TODO: change question)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def answer_question_1():\n",
    "    endpoint = \"https://api.example.com/endpoint\"\n",
    "    params = {\"query\": \"example\"}\n",
    "    headers = {\"Authorization\": f\"Bearer {API_KEY}\"}\n",
    "    data = fetch_data(endpoint, params, headers)\n",
    "\n",
    "    if data:\n",
    "        df = pd.DataFrame(data[\"results\"])\n",
    "        print(\"Top 5 Results:\")\n",
    "        print(df.head())  # Display top 5 results\n",
    "\n",
    "answer_question_1()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ### Q2: Analyze and sort data by a specific attribute\n",
    "TODO: change question in title"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def answer_question_2():\n",
    "    endpoint = \"https://api.example.com/another_endpoint\"\n",
    "    params = {\"search\": \"example_search\"}\n",
    "    headers = {\"Authorization\": f\"Bearer {API_KEY}\"}\n",
    "    data = fetch_data(endpoint, params, headers)\n",
    "\n",
    "    if data:\n",
    "        df = pd.DataFrame(data[\"results\"])\n",
    "        sorted_df = df.sort_values(\"rating\", ascending=False)  # Sort by rating\n",
    "        print(\"Sorted Results:\")\n",
    "        print(sorted_df.head())\n",
    "\n",
    "answer_question_2()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ### Q3: Filter results based on a condition\n",
    " TODO: change question in title"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "def answer_question_3():\n",
    "    endpoint = \"https://api.example.com/third_endpoint\"\n",
    "    params = {\"location\": \"example_location\"}\n",
    "    headers = {\"Authorization\": f\"Bearer {API_KEY}\"}\n",
    "    data = fetch_data(endpoint, params, headers)\n",
    "\n",
    "    if data:\n",
    "        df = pd.DataFrame(data[\"results\"])\n",
    "        filtered_df = df[df[\"rating\"] > 4.5]  # Filter by rating > 4.5\n",
    "        print(\"Filtered Results:\")\n",
    "        print(filtered_df)\n",
    "\n",
    "answer_question_3()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ### Q4: Optional - Visualizing data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "def visualize_question_4():\n",
    "    endpoint = \"https://api.example.com/fourth_endpoint\"\n",
    "    params = {\"term\": \"example_term\"}\n",
    "    headers = {\"Authorization\": f\"Bearer {API_KEY}\"}\n",
    "    data = fetch_data(endpoint, params, headers)\n",
    "\n",
    "    if data:\n",
    "        df = pd.DataFrame(data[\"results\"])\n",
    "        df[\"rating\"].value_counts().plot(kind=\"bar\")  # Plot a bar chart of ratings\n",
    "        plt.title(\"Distribution of Ratings\")\n",
    "        plt.xlabel(\"Rating\")\n",
    "        plt.ylabel(\"Frequency\")\n",
    "        plt.show()\n",
    "\n",
    "visualize_question_4()\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ## Submission"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " Complete this notebook, rename it to `A1-2.ipynb`, and submit it along with any necessary credentials or configuration files to the CourSys activity [`Assignment 1 - Part 2`](https://coursys.sfu.ca/2025sp-cmpt-733-g1/+a1-2/)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    " ## Submission Checklist\n",
    "\n",
    "\n",
    "\n",
    " - [ ] Completed notebook file (`A1-2.ipynb`).\n",
    "\n",
    " - [ ] Included API keys or other necessary credentials (if applicable).\n",
    "\n",
    " - [ ] Verified that questions and answers are documented with meaningful titles.\n",
    "\n",
    " - [ ] Optional visualizations are added to enhance insights."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": 3
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}