{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "bf5f7f59-8705-44c9-bad3-574328e3479e",
   "metadata": {},
   "source": [
    "# Get Median Earnings of High School Graduates by State (U.S. Census)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "91d48fa8-49ba-43a5-a96b-543f32d485ca",
   "metadata": {},
   "source": [
    "This script retrieves median annual earnings for high school graduates from the ACS survey. \n",
    "\n",
    "NOTE: In order to run this script, you will need an API key from the U.S. Census Bureau, which can be requested for free at https://api.census.gov/data/key_signup.html."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0814621d-3a9d-4fc6-8b4d-c32b5be63bee",
   "metadata": {},
   "source": [
    "### Step 1: Import required libraries."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "f55d5ce4-0427-477c-8e76-3b188320f14d",
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "import pandas as pd"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f4781e8-2d20-4ce0-bd10-35d173846447",
   "metadata": {},
   "source": [
    "### Step 2: Define the API key."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "b66b6364-a4a0-4060-91fd-28c245f8d45f",
   "metadata": {},
   "outputs": [],
   "source": [
    "api_key = \"INSERT YOUR API KEY HERE\" # Replace the text in quotation marks with your API key."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8dee2857-21b6-4d97-9b09-e3da3fd6df26",
   "metadata": {},
   "source": [
    "### Step 3: Define the survey year for retrieving the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "5d88290f-3acc-46f9-a33f-1b3656498d18",
   "metadata": {},
   "outputs": [],
   "source": [
    "year = \"2023\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c4fcf53-640e-4b12-ac7b-b0cdfe7d9c0f",
   "metadata": {},
   "source": [
    "### Step 4: Define the base URL for retrieving the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "cd025aa7-e56e-4a34-9e7b-a0bb7c169a99",
   "metadata": {},
   "outputs": [],
   "source": [
    "base_url = f\"https://api.census.gov/data/{year}/acs/acs1/subject\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e6810223-c977-4c58-8489-ad88c9329baa",
   "metadata": {},
   "source": [
    "### Step 5: Define the parameters for retrieving the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "a0f66a91-383e-4ffc-ac5b-07b9b796f2c6",
   "metadata": {},
   "outputs": [],
   "source": [
    "params = {\n",
    "    \"get\": \"NAME,S1501_C01_061E\", # Table and column reference for the data.\n",
    "    \"for\": \"state:*\",\n",
    "    \"key\": api_key\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7ef33079-6587-4849-8cca-f70fe527ff50",
   "metadata": {},
   "source": [
    "### Step 6: Use the API to call for the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "e72837e1-9730-4a6a-90ce-de26e9d5b0e0",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Data saved to median_high_school_earnings_by_state.csv\n"
     ]
    }
   ],
   "source": [
    "response = requests.get(base_url, params=params)\n",
    "\n",
    "if response.status_code == 200:\n",
    "    data = response.json()\n",
    "    headers = data[0]\n",
    "    rows = data[1:]\n",
    "    df = pd.DataFrame(rows, columns=headers)\n",
    "    df = df.rename(columns={\n",
    "        \"state\": \"State Code\",\n",
    "        \"NAME\": \"State Name\",\n",
    "        \"S1501_C01_061E\": \"Median HS Grad Earnings\",\n",
    "    })\n",
    "    df[\"Median HS Grad Earnings\"] = pd.to_numeric(df[\"Median HS Grad Earnings\"], errors='coerce')\n",
    "    df = df.sort_values(by=\"State Code\", ascending=True)\n",
    "\n",
    "    column_order = [\"State Code\", \"State Name\", \"Median HS Grad Earnings\"]\n",
    "\n",
    "    df = df[column_order]\n",
    "\n",
    "    df.to_csv(\"median_hs_earnings_by_state.csv\", index=False)\n",
    "    print(\"Data saved to median_high_school_earnings_by_state.csv\")\n",
    "else:\n",
    "    print(f\"Error fetching data: {response.status_code} - {response.text}\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:base] *",
   "language": "python",
   "name": "conda-base-py"
  },
  "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.12.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}