Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

7.5 KB
Raw Blame
{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# GeoDataFrame with Datetime Columns\n",
    "\n",
    "Demonstrates that `KeplerGl` handles GeoDataFrames containing\n",
    "`datetime` (and other non-JSON-native) columns when adding data\n",
    "and exporting to HTML.\n",
    "\n",
    "By default, `save_to_html` uses `default=str` when serializing\n",
    "GeoDataFrame data to GeoJSON, so datetime values are automatically\n",
    "converted to strings.  You can override this with the `json_encoder`\n",
    "parameter."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "import pandas as pd\n",
    "import geopandas"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create a GeoDataFrame with datetime columns"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>City</th>\n",
       "      <th>Country</th>\n",
       "      <th>Latitude</th>\n",
       "      <th>Longitude</th>\n",
       "      <th>Timestamp</th>\n",
       "      <th>geometry</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>Buenos Aires</td>\n",
       "      <td>Argentina</td>\n",
       "      <td>-34.58</td>\n",
       "      <td>-58.66</td>\n",
       "      <td>2024-01-15 08:00:00</td>\n",
       "      <td>POINT (-58.66 -34.58)</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>Brasilia</td>\n",
       "      <td>Brazil</td>\n",
       "      <td>-15.78</td>\n",
       "      <td>-47.91</td>\n",
       "      <td>2024-02-20 09:30:00</td>\n",
       "      <td>POINT (-47.91 -15.78)</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>Santiago</td>\n",
       "      <td>Chile</td>\n",
       "      <td>-33.45</td>\n",
       "      <td>-70.66</td>\n",
       "      <td>2024-03-10 11:00:00</td>\n",
       "      <td>POINT (-70.66 -33.45)</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>3</th>\n",
       "      <td>Bogota</td>\n",
       "      <td>Colombia</td>\n",
       "      <td>4.60</td>\n",
       "      <td>-74.08</td>\n",
       "      <td>2024-04-05 14:15:00</td>\n",
       "      <td>POINT (-74.08 4.6)</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>4</th>\n",
       "      <td>Caracas</td>\n",
       "      <td>Venezuela</td>\n",
       "      <td>10.48</td>\n",
       "      <td>-66.86</td>\n",
       "      <td>2024-05-22 16:45:00</td>\n",
       "      <td>POINT (-66.86 10.48)</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "           City    Country  Latitude  Longitude           Timestamp  \\\n",
       "0  Buenos Aires  Argentina    -34.58     -58.66 2024-01-15 08:00:00   \n",
       "1      Brasilia     Brazil    -15.78     -47.91 2024-02-20 09:30:00   \n",
       "2      Santiago      Chile    -33.45     -70.66 2024-03-10 11:00:00   \n",
       "3        Bogota   Colombia      4.60     -74.08 2024-04-05 14:15:00   \n",
       "4       Caracas  Venezuela     10.48     -66.86 2024-05-22 16:45:00   \n",
       "\n",
       "                geometry  \n",
       "0  POINT (-58.66 -34.58)  \n",
       "1  POINT (-47.91 -15.78)  \n",
       "2  POINT (-70.66 -33.45)  \n",
       "3     POINT (-74.08 4.6)  \n",
       "4   POINT (-66.86 10.48)  "
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "df = pd.DataFrame({\n",
    "    \"City\": [\"Buenos Aires\", \"Brasilia\", \"Santiago\", \"Bogota\", \"Caracas\"],\n",
    "    \"Country\": [\"Argentina\", \"Brazil\", \"Chile\", \"Colombia\", \"Venezuela\"],\n",
    "    \"Latitude\": [-34.58, -15.78, -33.45, 4.60, 10.48],\n",
    "    \"Longitude\": [-58.66, -47.91, -70.66, -74.08, -66.86],\n",
    "    \"Timestamp\": pd.to_datetime([\n",
    "        \"2024-01-15 08:00\",\n",
    "        \"2024-02-20 09:30\",\n",
    "        \"2024-03-10 11:00\",\n",
    "        \"2024-04-05 14:15\",\n",
    "        \"2024-05-22 16:45\",\n",
    "    ]),\n",
    "})\n",
    "\n",
    "gdf = geopandas.GeoDataFrame(\n",
    "    df, geometry=geopandas.points_from_xy(df.Longitude, df.Latitude)\n",
    ")\n",
    "display(gdf)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Load into kepler.gl"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "82b0ac8ca9fc49c7b2b9b29e46b3761f",
       "version_major": 2,
       "version_minor": 1
      },
      "text/plain": [
       "<keplergl.widget.KeplerGl object at 0x115f62000>"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import keplergl\n",
    "\n",
    "w = keplergl.KeplerGl(height=500)\n",
    "w"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "w.add_data(data=gdf, name=\"cities\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Export to HTML\n",
    "\n",
    "The default `json_encoder=str` converts datetime values automatically."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Map saved to datetime_map.html!\n"
     ]
    }
   ],
   "source": [
    "w.save_to_html(file_name=\"datetime_map.html\", read_only=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Custom json_encoder\n",
    "\n",
    "You can pass a custom function to control how non-serializable types\n",
    "are encoded.  For example, use `isoformat()` for ISO 8601 strings:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Map saved to datetime_map_iso.html!\n"
     ]
    }
   ],
   "source": [
    "w.save_to_html(\n",
    "    file_name=\"datetime_map_iso.html\",\n",
    "    read_only=True,\n",
    "    json_encoder=lambda o: o.isoformat() if hasattr(o, \"isoformat\") else str(o),\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "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.5"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}