Reference¶

GeoSeries¶

The following Shapely methods and attributes are available on GeoSeries objects:

GeoSeries.area¶: Returns a Series containing the area of each geometry in the GeoSeries.

GeoSeries.bounds¶

Returns a DataFrame with columns minx, miny, maxx, maxy values containing the bounds for each geometry.

See GeoSeries.total_bounds for the limits of the entire series.

GeoSeries.length¶: Returns a Series containing the length of each geometry.

GeoSeries.geom_type¶: Returns a Series of strings specifying the Geometry Type of each object.

GeoSeries.distance(other)¶

Returns a Series containing the distance to other.

Parameters:

other : Geoseries or geometric object

The Geoseries (elementwise) or geometric object to find the distance to.

GeoSeries.representative_point()¶: Returns a GeoSeries of (cheaply computed) points that are guaranteed to be within each geometry.

GeoSeries.exterior¶

Returns a GeoSeries of LinearRings representing the outer boundary of each polygon in the GeoSeries.

Applies to GeoSeries containing only Polygons.

GeoSeries.interiors¶

Returns a GeoSeries of InteriorRingSequences representing the inner rings of each polygon in the GeoSeries.

Applies to GeoSeries containing only Polygons.

Unary Predicates

GeoSeries.is_empty¶: Returns a Series of dtype('bool') with value True for empty geometries.

GeoSeries.is_ring¶: Returns a Series of dtype('bool') with value True for features that are closed.

GeoSeries.is_simple¶

Returns a Series of dtype('bool') with value True for geometries that do not cross themselves.

This is meaningful only for LineStrings and LinearRings.

GeoSeries.is_valid¶: Returns a Series of dtype('bool') with value True for geometries that are valid.

Binary Predicates

GeoSeries.geom_almost_equals(other, decimal=6)¶

Returns a Series of dtype('bool') with value True if each geometry is approximately equal to other.

Approximate equality is tested at all points to the specified decimal place precision. See also equals().

Parameters:

other : GeoSeries or geometric object

The GeoSeries (elementwise) or geometric object to compare to.

decimal : int

Decimal place presion used when testing for approximate equality.

GeoSeries.contains(other)¶

Returns a Series of dtype('bool') with value True for each geometry that contains other.

An object is said to contain other if its interior contains the boundary and interior of the other object and their boundaries do not touch at all.

This is the inverse of within() in the sense that the expression a.contains(b) == b.within(a) always evaluates to True.

Parameters:

other : GeoSeries or geometric object

The GeoSeries (elementwise) or geometric object to test if is contained.

GeoSeries.crosses(other)¶

Returns a Series of dtype('bool') with value True for each geometry that cross other.

An object is said to cross other if its interior intersects the interior of the other but does not contain it, and the dimension of the intersection is less than the dimension of the one or the other.

Parameters:

other : GeoSeries or geometric object

The GeoSeries (elementwise) or geometric object to test if is crossed.

GeoSeries.disjoint(other)¶

Returns a Series of dtype('bool') with value True for each geometry disjoint to other.

An object is said to be disjoint to other if its boundary and interior does not intersect at all with those of the other.

Parameters:

other : GeoSeries or geometric object

The GeoSeries (elementwise) or geometric object to test if is disjoint.

GeoSeries.geom_equals(other)¶

Returns a Series of dtype('bool') with value True for each geometry equal to other.

An object is said to be equal to other if its set-theoretic boundary, interior, and exterior coincides with those of the other.

Parameters:

other : GeoSeries or geometric object

The GeoSeries (elementwise) or geometric object to test for equality.

GeoSeries.intersects(other)¶

Returns a Series of dtype('bool') with value True for each geometry that intersects other.

An object is said to intersect other if its boundary and interior intersects in any way with those of the other.

Parameters:

other : GeoSeries or geometric object

The GeoSeries (elementwise) or geometric object to test if is intersected.

GeoSeries.touches(other)¶

Returns a Series of dtype('bool') with value True for each geometry that touches other.

An object is said to touch other if it has at least one point in common with other and its interior does not intersect with any part of the other.

Parameters:

other : GeoSeries or geometric object

The GeoSeries (elementwise) or geometric object to test if is touched.

GeoSeries.within(other)¶

Returns a Series of dtype('bool') with value True for each geometry that is within other.

An object is said to be within other if its boundary and interior intersects only with the interior of the other (not its boundary or exterior).

This is the inverse of contains() in the sense that the expression a.within(b) == b.contains(a) always evaluates to True.

Parameters:

other : GeoSeries or geometric object

The GeoSeries (elementwise) or geometric object to test if each geometry is within.

Set-theoretic Methods

GeoSeries.difference(other)¶

Returns a GeoSeries of the points in each geometry that are not in other.

Parameters:

other : Geoseries or geometric object

The Geoseries (elementwise) or geometric object to find the difference to.

GeoSeries.intersection(other)¶

Returns a GeoSeries of the intersection of points in each geometry with other.

Parameters:

other : Geoseries or geometric object

The Geoseries (elementwise) or geometric object to find the intersection with.

GeoSeries.symmetric_difference(other)¶

Returns a GeoSeries of the symmetric difference of points in each geometry with other.

For each geometry, the symmetric difference consists of points in the geometry not in other, and points in other not in the geometry.

Parameters:

other : Geoseries or geometric object

The Geoseries (elementwise) or geometric object to find the symmetric difference to.

GeoSeries.union(other)¶

Returns a GeoSeries of the union of points in each geometry with other.

Parameters:

other : Geoseries or geometric object

The Geoseries (elementwise) or geometric object to find the union with.

Constructive Methods

GeoSeries.buffer(distance, resolution=16, **kwargs)¶

Returns a GeoSeries of geometries representing all points within a given distance of each geometric object.

See http://shapely.readthedocs.io/en/latest/manual.html#object.buffer for details.

Parameters:

distance : float

The radius of the buffer.

resolution: float

Optional, the resolution of the buffer around each vertex.

GeoSeries.boundary¶: Returns a GeoSeries of lower dimensional objects representing each geometries’s set-theoretic boundary.

GeoSeries.centroid¶: Returns a GeoSeries of points representing the centroid of each geometry.

GeoSeries.convex_hull¶

Returns a GeoSeries of geometries representing the convex hull of each geometry.

The convex hull of a geometry is the smallest convex Polygon containing all the points in each geometry, unless the number of points in the geometric object is less than three. For two points, the convex hull collapses to a LineString; for 1, a Point.

GeoSeries.envelope¶

Returns a GeoSeries of geometries representing the envelope of each geometry.

The envelope of a geometry is the bounding rectangle. That is, the point or smallest rectangular polygon (with sides parallel to the coordinate axes) that contains the geometry.

GeoSeries.simplify(*args, **kwargs)¶

Returns a GeoSeries containing a simplified representation of each geometry.

See http://shapely.readthedocs.io/en/latest/manual.html#object.simplify for details

Parameters:

tolerance : float

All points in a simplified geometry will be no more than tolerance distance from the original.

preserve_topology: bool

False uses a quicker algorithm, but may produce self-intersecting or otherwise invalid geometries.

Affine transformations

GeoSeries.rotate(angle, origin='center', use_radians=False)¶

Returns a GeoSeries with rotated geometries.

See http://shapely.readthedocs.io/en/latest/manual.html#shapely.affinity.rotate for details.

Parameters:

angle : float

The angle of rotation can be specified in either degrees (default) or radians by setting use_radians=True. Positive angles are counter-clockwise and negative are clockwise rotations.

origin : string, Point, or tuple (x, y)

The point of origin can be a keyword ‘center’ for the bounding box center (default), ‘centroid’ for the geometry’s centroid, a Point object or a coordinate tuple (x, y).

use_radians : boolean

Whether to interpret the angle of rotation as degrees or radians

GeoSeries.scale(xfact=1.0, yfact=1.0, zfact=1.0, origin='center')¶

Returns a GeoSeries with scaled geometries.

The geometries can be scaled by different factors along each dimension. Negative scale factors will mirror or reflect coordinates.

See http://shapely.readthedocs.io/en/latest/manual.html#shapely.affinity.scale for details.

Parameters:

xfact, yfact, zfact : float, float, float

Scaling factors for the x, y, and z dimensions respectively.

origin : string, Point, or tuple

The point of origin can be a keyword ‘center’ for the 2D bounding box center (default), ‘centroid’ for the geometry’s 2D centroid, a Point object or a coordinate tuple (x, y, z).

GeoSeries.skew(xs=0.0, ys=0.0, origin='center', use_radians=False)¶

Returns a GeoSeries with skewed geometries.

The geometries are sheared by angles along the x and y dimensions.

See http://shapely.readthedocs.io/en/latest/manual.html#shapely.affinity.skew for details.

Parameters:

xs, ys : float, float

The shear angle(s) for the x and y axes respectively. These can be specified in either degrees (default) or radians by setting use_radians=True.

origin : string, Point, or tuple (x, y)

The point of origin can be a keyword ‘center’ for the bounding box center (default), ‘centroid’ for the geometry’s centroid, a Point object or a coordinate tuple (x, y).

use_radians : boolean

Whether to interpret the shear angle(s) as degrees or radians

GeoSeries.translate(xoff=0.0, yoff=0.0, zoff=0.0)¶

Returns a GeoSeries with translated geometries.

See http://shapely.readthedocs.io/en/latest/manual.html#shapely.affinity.translate for details.

Parameters:

xoff, yoff, zoff : float, float, float

Amount of offset along each dimension. xoff, yoff, and zoff for translation along the x, y, and z dimensions respectively.

Aggregating methods

GeoSeries.unary_union¶: Returns a geometry containing the union of all geometries in the GeoSeries.

Additionally, the following methods are implemented:

classmethod GeoSeries.from_file(filename, **kwargs)¶

Alternate constructor to create a GeoSeries from a file.

Can load a GeoSeries from a file from any format recognized by fiona. See http://toblerity.org/fiona/manual.html for details.

Parameters:

filename : str

File path or file handle to read from. Depending on which kwargs are included, the content of filename may vary. See http://toblerity.org/fiona/README.html#usage for usage details.

kwargs : key-word arguments

These arguments are passed to fiona.open, and can be used to access multi-layer data, data stored within archives (zip files), etc.

GeoSeries.to_crs(crs=None, epsg=None)¶

Returns a GeoSeries with all geometries transformed to a new coordinate reference system.

Transform all geometries in a GeoSeries to a different coordinate reference system. The crs attribute on the current GeoSeries must be set. Either crs in string or dictionary form or an EPSG code may be specified for output.

This method will transform all points in all objects. It has no notion or projecting entire geometries. All segments joining points are assumed to be lines in the current projection, not geodesics. Objects crossing the dateline (or other projection boundary) will have undesirable behavior.

Parameters:

crs : dict or str

Output projection parameters as string or in dictionary form.

epsg : int

EPSG code specifying output projection.

GeoSeries.plot(*args, **kwargs)¶

Plot a GeoSeries.

Generate a plot of a GeoSeries geometry with matplotlib.

Parameters:

s : Series

The GeoSeries to be plotted. Currently Polygon, MultiPolygon, LineString, MultiLineString and Point geometries can be plotted.

cmap : str (default None)

The name of a colormap recognized by matplotlib. Any colormap will work, but categorical colormaps are generally recommended. Examples of useful discrete colormaps include:

tab10, tab20, Accent, Dark2, Paired, Pastel1, Set1, Set2

color : str (default None)

If specified, all objects will be colored uniformly.

ax : matplotlib.pyplot.Artist (default None)

axes on which to draw the plot

figsize : pair of floats (default None)

Size of the resulting matplotlib.figure.Figure. If the argument ax is given explicitly, figsize is ignored.

**style_kwds : dict

Color options to be passed on to the actual plot function, such as edgecolor, facecolor, linewidth, markersize, alpha.

Returns:

ax : matplotlib axes instance

GeoSeries.total_bounds¶

Returns a tuple containing minx, miny, maxx, maxy values for the bounds of the series as a whole.

See GeoSeries.bounds for the bounds of the geometries contained in the series.

GeoSeries.__geo_interface__¶

Returns a GeoSeries as a python feature collection.

Implements the geo_interface. The returned python data structure represents the GeoSeries as a GeoJSON-like FeatureCollection. Note that the features will have an empty properties dict as they don’t have associated attributes (geometry only).

Methods of pandas Series objects are also available, although not all are applicable to geometric objects and some may return a Series rather than a GeoSeries result. The methods copy(), align(), isnull() and fillna() have been implemented specifically for GeoSeries and are expected to work correctly.

GeoDataFrame¶

A GeoDataFrame is a tablular data structure that contains a column called geometry which contains a GeoSeries`.

Currently, the following methods are implemented for a GeoDataFrame:

classmethod GeoDataFrame.from_file(filename, **kwargs)¶

Alternate constructor to create a GeoDataFrame from a file.

Can load a GeoDataFrame from a file in any format recognized by fiona. See http://toblerity.org/fiona/manual.html for details.

Parameters:

filename : str

File path or file handle to read from. Depending on which kwargs are included, the content of filename may vary. See http://toblerity.org/fiona/README.html#usage for usage details.

kwargs : key-word arguments

These arguments are passed to fiona.open, and can be used to access multi-layer data, data stored within archives (zip files), etc.

Examples

>>> df = geopandas.GeoDataFrame.from_file('nybb.shp')

classmethod GeoDataFrame.from_postgis(sql, con, geom_col='geom', crs=None, hex_encoded=True, index_col=None, coerce_float=True, params=None)¶

Alternate constructor to create a GeoDataFrame from a sql query containing a geometry column.

Parameters:

sql : string

con : DB connection object or SQLAlchemy engine

geom_col : string, default ‘geom’

column name to convert to shapely geometries

crs : optional

Coordinate reference system to use for the returned GeoDataFrame

hex_encoded : bool, optional

Whether the geometry is in a hex-encoded string. Default is True, standard for postGIS.

index_col : string or list of strings, optional, default: None

Column(s) to set as index(MultiIndex)

coerce_float : boolean, default True

Attempt to convert values of non-string, non-numeric objects (like decimal.Decimal) to floating point, useful for SQL result sets

params : list, tuple or dict, optional, default: None

List of parameters to pass to execute method.

Examples

>>> sql = "SELECT geom, highway FROM roads;"
>>> df = geopandas.GeoDataFrame.from_postgis(sql, con)

GeoDataFrame.to_crs(crs=None, epsg=None, inplace=False)¶

Transform geometries to a new coordinate reference system.

Transform all geometries in a GeoSeries to a different coordinate reference system. The crs attribute on the current GeoSeries must be set. Either crs in string or dictionary form or an EPSG code may be specified for output.

This method will transform all points in all objects. It has no notion or projecting entire geometries. All segments joining points are assumed to be lines in the current projection, not geodesics. Objects crossing the dateline (or other projection boundary) will have undesirable behavior.

Parameters:

crs : dict or str

Output projection parameters as string or in dictionary form.

epsg : int

EPSG code specifying output projection.

inplace : bool, optional, default: False

Whether to return a new GeoDataFrame or do the transformation in place.

GeoDataFrame.to_file(filename, driver='ESRI Shapefile', schema=None, **kwargs)¶

Write the GeoDataFrame to a file.

By default, an ESRI shapefile is written, but any OGR data source supported by Fiona can be written. A dictionary of supported OGR providers is available via:

>>> import fiona
>>> fiona.supported_drivers

Parameters:

filename : string

File path or file handle to write to.

driver : string, default: ‘ESRI Shapefile’

The OGR format driver used to write the vector file.

schema : dict, default: None

If specified, the schema dictionary is passed to Fiona to better control how the file is written.

Notes

The extra keyword arguments **kwargs are passed to fiona.open and can be used to write to multi-layer data, store data within archives (zip files), etc.

GeoDataFrame.to_json(na='null', show_bbox=False, **kwargs)¶

Returns a GeoJSON representation of the GeoDataFrame as a string.

Parameters:

na : {‘null’, ‘drop’, ‘keep’}, default ‘null’

Indicates how to output missing (NaN) values in the GeoDataFrame. See below.

show_bbox : bool, optional, default: False

Include bbox (bounds) in the geojson

Notes

The remaining kwargs are passed to json.dumps().

Missing (NaN) values in the GeoDataFrame can be represented as follows:

null: output the missing entries as JSON null.
drop: remove the property from the feature. This applies to each feature individually so that features may have different properties.
keep: output the missing entries as NaN.

GeoDataFrame.plot(*args, **kwargs)¶

Plot a GeoDataFrame.

Generate a plot of a GeoDataFrame with matplotlib. If a column is specified, the plot coloring will be based on values in that column.

Parameters:

df : GeoDataFrame

The GeoDataFrame to be plotted. Currently Polygon, MultiPolygon, LineString, MultiLineString and Point geometries can be plotted.

column : str, np.array, pd.Series (default None)

The name of the dataframe column, np.array, or pd.Series to be plotted. If np.array or pd.Series are used then it must have same length as dataframe. Values are used to color the plot. Ignored if color is also set.

cmap : str (default None)

The name of a colormap recognized by matplotlib.

color : str (default None)

If specified, all objects will be colored uniformly.

ax : matplotlib.pyplot.Artist (default None)

axes on which to draw the plot

categorical : bool (default False)

If False, cmap will reflect numerical values of the column being plotted. For non-numerical columns, this will be set to True.

legend : bool (default False)

Plot a legend. Ignored if no column is given, or if color is given.

scheme : str (default None)

Name of a choropleth classification scheme (requires PySAL). A pysal.esda.mapclassify.Map_Classifier object will be used under the hood. Supported schemes: ‘Equal_interval’, ‘Quantiles’, ‘Fisher_Jenks’

k : int (default 5)

Number of classes (ignored if scheme is None)

vmin : None or float (default None)

Minimum value of cmap. If None, the minimum data value in the column to be plotted is used.

vmax : None or float (default None)

Maximum value of cmap. If None, the maximum data value in the column to be plotted is used.

markersize : str or float or sequence (default None)

Only applies to point geometries within a frame. If a str, will use the values in the column of the frame specified by markersize to set the size of markers. Otherwise can be a value to apply to all points, or a sequence of the same length as the number of points.

figsize : tuple of integers (default None)

Size of the resulting matplotlib.figure.Figure. If the argument axes is given explicitly, figsize is ignored.

legend_kwds : dict (default None)

Keyword arguments to pass to ax.legend()

**style_kwds : dict

Color options to be passed on to the actual plot function, such as edgecolor, facecolor, linewidth, markersize, alpha.

Returns:

ax : matplotlib axes instance

GeoDataFrame.__geo_interface__¶

Returns a GeoDataFrame as a python feature collection.

Implements the geo_interface. The returned python data structure represents the GeoDataFrame as a GeoJSON-like FeatureCollection.

This differs from _to_geo() only in that it is a property with default args instead of a method

All pandas DataFrame methods are also available, although they may not operate in a meaningful way on the geometry column and may not return a GeoDataFrame result even when it would be appropriate to do so.

API Pages¶

`GeoDataFrame`(args, *kwargs)	A GeoDataFrame object is a pandas.DataFrame that has a column with geometry.
`GeoSeries`(args, *kwargs)	A Series object designed to store shapely geometry objects.
`overlay`(df1, df2[, how, make_valid, use_sindex])	Perform spatial overlay between two polygons.
`read_file`(filename[, bbox])	Returns a GeoDataFrame from a file or URL.
`sjoin`(left_df, right_df[, how, op, lsuffix, …])	Spatial join of two GeoDataFrames.
`tools.geocode`(strings[, provider])	Geocode a set of strings and get a GeoDataFrame of the resulting points.
`datasets.get_path`(dataset)	Get the path to the data file.