README.md
1GeoPandas [](https://github.com/geopandas/geopandas/actions?query=workflow%3ATests) [](https://codecov.io/gh/geopandas/geopandas) [](https://gitter.im/geopandas/geopandas?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) [](https://mybinder.org/v2/gh/geopandas/geopandas/master) [](https://zenodo.org/badge/latestdoi/11002815)
2=========
3
4Python tools for geographic data
5
6Introduction
7------------
8
9GeoPandas is a project to add support for geographic data to
10[pandas](http://pandas.pydata.org) objects. It currently implements
11`GeoSeries` and `GeoDataFrame` types which are subclasses of
12`pandas.Series` and `pandas.DataFrame` respectively. GeoPandas
13objects can act on [shapely](http://shapely.readthedocs.io/en/latest/)
14geometry objects and perform geometric operations.
15
16GeoPandas geometry operations are cartesian. The coordinate reference
17system (crs) can be stored as an attribute on an object, and is
18automatically set when loading from a file. Objects may be
19transformed to new coordinate systems with the `to_crs()` method.
20There is currently no enforcement of like coordinates for operations,
21but that may change in the future.
22
23Documentation is available at [geopandas.org](http://geopandas.org)
24(current release) and
25[Read the Docs](http://geopandas.readthedocs.io/en/latest/)
26(release and development versions).
27
28Install
29--------
30
31See the [installation docs](https://geopandas.readthedocs.io/en/latest/install.html)
32for all details. GeoPandas depends on the following packages:
33
34- ``pandas``
35- ``shapely``
36- ``fiona``
37- ``pyproj``
38
39Further, ``matplotlib`` is an optional dependency, required
40for plotting, and [``rtree``](https://github.com/Toblerity/rtree) is an optional
41dependency, required for spatial joins. ``rtree`` requires the C library [``libspatialindex``](https://github.com/libspatialindex/libspatialindex).
42
43Those packages depend on several low-level libraries for geospatial analysis, which can be a challenge to install. Therefore, we recommend to install GeoPandas using the [conda package manager](https://conda.io/en/latest/). See the [installation docs](https://geopandas.readthedocs.io/en/latest/install.html) for more details.
44
45
46Get in touch
47------------
48
49- Ask usage questions ("How do I?") on [StackOverflow](https://stackoverflow.com/questions/tagged/geopandas) or [GIS StackExchange](https://gis.stackexchange.com/questions/tagged/geopandas).
50- Report bugs, suggest features or view the source code [on GitHub](https://github.com/geopandas/geopandas).
51- For a quick question about a bug report or feature request, or Pull Request, head over to the [gitter channel](https://gitter.im/geopandas/geopandas).
52- For less well defined questions or ideas, or to announce other projects of interest to GeoPandas users, ... use the [mailing list](https://groups.google.com/forum/#!forum/geopandas).
53
54
55Examples
56--------
57
58 >>> import geopandas
59 >>> from shapely.geometry import Polygon
60 >>> p1 = Polygon([(0, 0), (1, 0), (1, 1)])
61 >>> p2 = Polygon([(0, 0), (1, 0), (1, 1), (0, 1)])
62 >>> p3 = Polygon([(2, 0), (3, 0), (3, 1), (2, 1)])
63 >>> g = geopandas.GeoSeries([p1, p2, p3])
64 >>> g
65 0 POLYGON ((0 0, 1 0, 1 1, 0 0))
66 1 POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))
67 2 POLYGON ((2 0, 3 0, 3 1, 2 1, 2 0))
68 dtype: geometry
69
70
71
72Some geographic operations return normal pandas object. The `area` property of a `GeoSeries` will return a `pandas.Series` containing the area of each item in the `GeoSeries`:
73
74 >>> print(g.area)
75 0 0.5
76 1 1.0
77 2 1.0
78 dtype: float64
79
80Other operations return GeoPandas objects:
81
82 >>> g.buffer(0.5)
83 0 POLYGON ((-0.3535533905932737 0.35355339059327...
84 1 POLYGON ((-0.5 0, -0.5 1, -0.4975923633360985 ...
85 2 POLYGON ((1.5 0, 1.5 1, 1.502407636663901 1.04...
86 dtype: geometry
87
88
89
90GeoPandas objects also know how to plot themselves. GeoPandas uses
91[matplotlib](http://matplotlib.org) for plotting. To generate a plot of our
92GeoSeries, use:
93
94 >>> g.plot()
95
96GeoPandas also implements alternate constructors that can read any data format recognized by [fiona](http://fiona.readthedocs.io/en/latest/). To read a zip file containing an ESRI shapefile with the [boroughs boundaries of New York City](https://data.cityofnewyork.us/City-Government/Borough-Boundaries/tqmj-j8zm) (GeoPandas includes this as an example dataset):
97
98 >>> nybb_path = geopandas.datasets.get_path('nybb')
99 >>> boros = geopandas.read_file(nybb_path)
100 >>> boros.set_index('BoroCode', inplace=True)
101 >>> boros.sort_index(inplace=True)
102 >>> boros
103 BoroName Shape_Leng Shape_Area \
104 BoroCode
105 1 Manhattan 359299.096471 6.364715e+08
106 2 Bronx 464392.991824 1.186925e+09
107 3 Brooklyn 741080.523166 1.937479e+09
108 4 Queens 896344.047763 3.045213e+09
109 5 Staten Island 330470.010332 1.623820e+09
110
111 geometry
112 BoroCode
113 1 MULTIPOLYGON (((981219.0557861328 188655.31579...
114 2 MULTIPOLYGON (((1012821.805786133 229228.26458...
115 3 MULTIPOLYGON (((1021176.479003906 151374.79699...
116 4 MULTIPOLYGON (((1029606.076599121 156073.81420...
117 5 MULTIPOLYGON (((970217.0223999023 145643.33221...
118
119
120
121 >>> boros['geometry'].convex_hull
122 BoroCode
123 1 POLYGON ((977855.4451904297 188082.3223876953,...
124 2 POLYGON ((1017949.977600098 225426.8845825195,...
125 3 POLYGON ((988872.8212280273 146772.0317993164,...
126 4 POLYGON ((1000721.531799316 136681.776184082, ...
127 5 POLYGON ((915517.6877458114 120121.8812543372,...
128 dtype: geometry
129
130
131
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
