This quick tutorial introduces the key concepts and basic features of GeoPandas to help you get started with your projects.

GeoPandas, as the name suggests, extends the popular data science library pandas by adding support for geospatial data. If you are not familiar with `pandas`

, we recommend taking a quick look at its Getting started documentation before proceeding.

The core data structure in GeoPandas is the `geopandas.GeoDataFrame`

, a subclass of `pandas.DataFrame`

, that can store geometry columns and perform spatial operations. The `geopandas.GeoSeries`

, a subclass of `pandas.Series`

, handles the geometries. Therefore, your `GeoDataFrame`

is a combination of `pandas.Series`

, with traditional data (numerical, boolean, text etc.), and `geopandas.GeoSeries`

, with geometries (points, polygons etc.). You can have as many columns with geometries as you wish; there's no limit typical for desktop GIS software.

Each `GeoSeries`

can contain any geometry type (you can even mix them within a single array) and has a `GeoSeries.crs`

attribute, which stores information about the projection (CRS stands for Coordinate Reference System). Therefore, each `GeoSeries`

in a `GeoDataFrame`

can be in a different projection, allowing you to have, for example, multiple versions (different projections) of the same geometry.

Only one `GeoSeries`

in a `GeoDataFrame`

is considered the *active* geometry, which means that all geometric operations applied to a `GeoDataFrame`

operate on this *active* column.

User guide

See more on data structures in the user guide.

Let's see how some of these concepts work in practice.

First, we need to read some data.

Assuming you have a file containing both data and geometry (e.g. GeoPackage, GeoJSON, Shapefile), you can read it using `geopandas.read_file()`

, which automatically detects the filetype and creates a `GeoDataFrame`

. This tutorial uses the `"nybb"`

dataset, a map of New York boroughs, which is available through the `geodatasets`

package. Therefore, we use `geodatasets.get_path()`

to download the dataset and retrieve the path to the local copy.

In [ ]:

```
import geopandas
from geodatasets import get_path
path_to_data = get_path("nybb")
gdf = geopandas.read_file(path_to_data)
gdf
```

To write a `GeoDataFrame`

back to file use `GeoDataFrame.to_file()`

. The default file format is Shapefile, but you can specify your own with the `driver`

keyword.

In [ ]:

```
gdf.to_file("my_file.geojson", driver="GeoJSON")
```

User guide

See more on reading and writing files in the user guide.

Now we have our `GeoDataFrame`

and can start working with its geometry.

Since there was only one geometry column in the New York Boroughs dataset, this column automatically becomes the *active* geometry and spatial methods used on the `GeoDataFrame`

will be applied to the `"geometry"`

column.

To measure the area of each polygon (or MultiPolygon in this specific case), access the `GeoDataFrame.area`

attribute, which returns a `pandas.Series`

. Note that `GeoDataFrame.area`

is just `GeoSeries.area`

applied to the *active* geometry column.

But first, to make the results easier to read, set the names of the boroughs as the index:

In [ ]:

```
gdf = gdf.set_index("BoroName")
```

In [ ]:

```
gdf["area"] = gdf.area
gdf["area"]
```

To get the boundary of each polygon (LineString), access the `GeoDataFrame.boundary`

:

In [ ]:

```
gdf["boundary"] = gdf.boundary
gdf["boundary"]
```

Since we have saved boundary as a new column, we now have two geometry columns in the same `GeoDataFrame`

.

We can also create new geometries, which could be, for example, a buffered version of the original one (i.e., `GeoDataFrame.buffer(10)`

) or its centroid:

In [ ]:

```
gdf["centroid"] = gdf.centroid
gdf["centroid"]
```

We can also measure how far each centroid is from the first centroid location.

In [ ]:

```
first_point = gdf["centroid"].iloc[0]
gdf["distance"] = gdf["centroid"].distance(first_point)
gdf["distance"]
```

Note that `geopandas.GeoDataFrame`

is a subclass of `pandas.DataFrame`

, so we have all the pandas functionality available to use on the geospatial dataset — we can even perform data manipulations with the attributes and geometry information together.

For example, to calculate the average of the distances measured above, access the 'distance' column and call the mean() method on it:

In [ ]:

```
gdf["distance"].mean()
```

GeoPandas can also plot maps, so we can check how the geometries appear in space. To plot the active geometry, call `GeoDataFrame.plot()`

. To color code by another column, pass in that column as the first argument. In the example below, we plot the active geometry column and color code by the `"area"`

column. We also want to show a legend (`legend=True`

).

In [ ]:

```
gdf.plot("area", legend=True)
```

`GeoDataFrame.explore()`

, which behaves in the same way `plot()`

does but returns an interactive map instead.

In [ ]:

```
gdf.explore("area", legend=False)
```

`GeoDataFrame.set_geometry`

) to centroids, we can plot the same data using point geometry.

In [ ]:

```
gdf = gdf.set_geometry("centroid")
gdf.plot("area", legend=True)
```

`GeoSeries`

on top of each other. We just need to use one plot as an axis for the other.

In [ ]:

```
ax = gdf["geometry"].plot()
gdf["centroid"].plot(ax=ax, color="black")
```

Now we set the active geometry back to the original `GeoSeries`

.

In [ ]:

```
gdf = gdf.set_geometry("geometry")
```

In [ ]:

```
gdf["convex_hull"] = gdf.convex_hull
```

In [ ]:

```
# saving the first plot as an axis and setting alpha (transparency) to 0.5
ax = gdf["convex_hull"].plot(alpha=0.5)
# passing the first plot and setting linewitdth to 0.5
gdf["boundary"].plot(ax=ax, color="white", linewidth=0.5)
```

In other cases, we may need to buffer the geometry using `GeoDataFrame.buffer()`

. Geometry methods are automatically applied to the active geometry, but we can apply them directly to any `GeoSeries`

as well. Let's buffer the boroughs and their centroids and plot both on top of each other.

In [ ]:

```
# buffering the active geometry by 10 000 feet (geometry is already in feet)
gdf["buffered"] = gdf.buffer(10000)
# buffering the centroid geometry by 10 000 feet (geometry is already in feet)
gdf["buffered_centroid"] = gdf["centroid"].buffer(10000)
```

In [ ]:

```
# saving the first plot as an axis and setting alpha (transparency) to 0.5
ax = gdf["buffered"].plot(alpha=0.5)
# passing the first plot as an axis to the second
gdf["buffered_centroid"].plot(ax=ax, color="red", alpha=0.5)
# passing the first plot and setting linewitdth to 0.5
gdf["boundary"].plot(ax=ax, color="white", linewidth=0.5)
```

User guide

See more on geometry manipulations in the user guide.

We can also ask about the spatial relations of different geometries. Using the geometries above, we can check which of the buffered boroughs intersect the original geometry of Brooklyn, i.e., is within 10 000 feet from Brooklyn.

First, we get a polygon of Brooklyn.

In [ ]:

```
brooklyn = gdf.loc["Brooklyn", "geometry"]
brooklyn
```

The polygon is a shapely geometry object, as any other geometry used in GeoPandas.

In [ ]:

```
type(brooklyn)
```

Then we can check which of the geometries in `gdf["buffered"]`

intersects it.

In [ ]:

```
gdf["buffered"].intersects(brooklyn)
```

Only Bronx (on the north) is more than 10 000 feet away from Brooklyn. All the others are closer and intersect our polygon.

Alternatively, we can check which buffered centroids are entirely within the original boroughs polygons. In this case, both `GeoSeries`

are aligned, and the check is performed for each row.

In [ ]:

```
gdf["within"] = gdf["buffered_centroid"].within(gdf)
gdf["within"]
```

We can plot the results on the map to confirm the finding.

In [ ]:

```
gdf = gdf.set_geometry("buffered_centroid")
# using categorical plot and setting the position of the legend
ax = gdf.plot(
"within", legend=True, categorical=True, legend_kwds={"loc": "upper left"}
)
# passing the first plot and setting linewitdth to 0.5
gdf["boundary"].plot(ax=ax, color="black", linewidth=0.5)
```

Each `GeoSeries`

has its Coordinate Reference System (CRS) accessible at `GeoSeries.crs`

. The CRS tells GeoPandas where the coordinates of the geometries are located on the earth's surface. In some cases, the CRS is geographic, which means that the coordinates are in latitude and longitude. In those cases, its CRS is WGS84, with the authority code `EPSG:4326`

. Let's see the projection of our NY boroughs `GeoDataFrame`

.

In [ ]:

```
gdf.crs
```

`EPSG:2263`

with coordinates in feet. We can easily re-project a `GeoSeries`

to another CRS, like `EPSG:4326`

using `GeoSeries.to_crs()`

.

In [ ]:

```
gdf = gdf.set_geometry("geometry")
boroughs_4326 = gdf.to_crs("EPSG:4326")
boroughs_4326.plot()
```

In [ ]:

```
boroughs_4326.crs
```

Notice the difference in coordinates along the axes of the plot. Where we had 120 000 - 280 000 (feet) before, we now have 40.5 - 40.9 (degrees). In this case, `boroughs_4326`

has a `"geometry"`

column in WGS84 but all the other (with centroids etc.) remain in the original CRS.

Warning

For operations that rely on distance or area, you always need to use a projected CRS (in meters, feet, kilometers etc.) not a geographic one (in degrees). GeoPandas operations are planar, whereas degrees reflect the position on a sphere. Therefore, spatial operations using degrees may not yield correct results. For example, the result of `gdf.area.sum()`

(projected CRS) is 8 429 911 572 ft^{2} but the result of `boroughs_4326.area.sum()`

(geographic CRS) is 0.083.

User guide

See more on projections in the user guide.

With GeoPandas we can do much more than what has been introduced so far, from aggregations, to spatial joins, to geocoding, and much more.

Head over to the user guide to learn more about the different features of GeoPandas, the Examples to see how they can be used, or to the API reference for the details.