Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
{
"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
}