0
# File I/O Operations
1

2
GeoPandas provides comprehensive support for reading and writing various geospatial file formats including Shapefile, GeoJSON, GeoPackage, Parquet, and database connections. The I/O functions integrate with multiple backends (Fiona, PyOGRIO) and support spatial filtering, column selection, and format-specific options.
3

4
## Capabilities
5

6
### Reading Geospatial Files
7

8
Functions for reading various geospatial file formats into GeoDataFrames.
9

10
```python { .api }
11
def read_file(filename, bbox=None, mask=None, rows=None, engine='auto', **kwargs):
12
    """
13
    Read geospatial file into GeoDataFrame.
14
    
15
    Parameters:
16
    - filename: Path to file or file-like object
17
    - bbox: Bounding box to filter features (minx, miny, maxx, maxy)
18
    - mask: Geometry or GeoDataFrame to spatially filter features
19
    - rows: Number of rows to read or slice object
20
    - engine: Backend engine ('auto', 'fiona', 'pyogrio')
21
    - **kwargs: Additional parameters for the backend
22
    
23
    Returns:
24
    - GeoDataFrame: Loaded geospatial data
25
    """
26
    ...
27

28
def read_parquet(path, columns=None, storage_options=None, bbox=None, **kwargs):
29
    """
30
    Read Parquet file with geometry data into GeoDataFrame.
31
    
32
    Parameters:
33
    - path: Path to Parquet file
34
    - columns: List of columns to read
35
    - storage_options: Storage options for cloud storage
36
    - bbox: Bounding box to filter features (minx, miny, maxx, maxy)
37
    - **kwargs: Additional parameters for pyarrow
38
    
39
    Returns:
40
    - GeoDataFrame: Loaded geospatial data
41
    """
42
    ...
43

44
def read_feather(path, columns=None, **kwargs):
45
    """
46
    Read Feather file with geometry data into GeoDataFrame.
47
    
48
    Parameters:
49
    - path: Path to Feather file
50
    - columns: List of columns to read
51
    - **kwargs: Additional parameters for pyarrow
52
    
53
    Returns:
54
    - GeoDataFrame: Loaded geospatial data
55
    """
56
    ...
57

58
def read_postgis(sql, con, geom_col='geom', crs=None, index_col=None, coerce_float=True, parse_dates=None, params=None, chunksize=None):
59
    """
60
    Read PostGIS database table into GeoDataFrame.
61
    
62
    Parameters:
63
    - sql: SQL query or table name
64
    - con: Database connection
65
    - geom_col: Name of geometry column
66
    - crs: Coordinate reference system
67
    - index_col: Column to use as index
68
    - coerce_float: Convert decimal to float
69
    - parse_dates: Columns to parse as dates
70
    - params: Parameters for parameterized queries
71
    - chunksize: Number of rows per chunk
72
    
73
    Returns:
74
    - GeoDataFrame: Loaded geospatial data
75
    """
76
    ...
77

78
def list_layers(filename):
79
    """
80
    List available layers in geospatial file.
81
    
82
    Parameters:
83
    - filename: Path to geospatial file
84
    
85
    Returns:
86
    - pandas.DataFrame: Information about available layers
87
    """
88
    ...
89
```
90

91
### Writing Geospatial Files
92

93
Methods available on GeoDataFrame and GeoSeries for writing to various formats.
94

95
```python { .api }
96
class GeoDataFrame:
97
    def to_file(self, filename, driver=None, index=None, mode='w', crs=None, engine='auto', **kwargs):
98
        """
99
        Write GeoDataFrame to geospatial file.
100
        
101
        Parameters:
102
        - filename: Output file path
103
        - driver: Output format driver ('ESRI Shapefile', 'GeoJSON', 'GPKG', etc.)
104
        - index: Whether to write index
105
        - mode: File mode ('w' for write, 'a' for append)
106
        - crs: Coordinate reference system for output
107
        - engine: Backend engine ('auto', 'fiona', 'pyogrio')
108
        - **kwargs: Driver-specific parameters
109
        """
110
        ...
111
    
112
    def to_parquet(self, path, index=None, compression='snappy', geometry_encoding='WKB', **kwargs):
113
        """
114
        Write GeoDataFrame to Parquet file.
115
        
116
        Parameters:
117
        - path: Output file path
118
        - index: Whether to write index
119
        - compression: Compression algorithm ('snappy', 'gzip', 'brotli', etc.)
120
        - geometry_encoding: Geometry encoding ('WKB', 'WKT', 'geoarrow')
121
        - **kwargs: Additional parameters for pyarrow
122
        """
123
        ...
124
    
125
    def to_feather(self, path, index=None, compression=None, **kwargs):
126
        """
127
        Write GeoDataFrame to Feather file.
128
        
129
        Parameters:
130
        - path: Output file path
131
        - index: Whether to write index
132
        - compression: Compression algorithm
133
        - **kwargs: Additional parameters for pyarrow
134
        """
135
        ...
136
    
137
    def to_postgis(self, name, con, schema=None, if_exists='fail', index=True, index_label=None, chunksize=None, dtype=None, method=None):
138
        """
139
        Write GeoDataFrame to PostGIS database table.
140
        
141
        Parameters:
142
        - name: Table name
143
        - con: Database connection
144
        - schema: Database schema
145
        - if_exists: What to do if table exists ('fail', 'replace', 'append')
146
        - index: Whether to write index
147
        - index_label: Label for index column
148
        - chunksize: Number of rows per chunk
149
        - dtype: Data types for columns
150
        - method: Method for inserting data
151
        """
152
        ...
153
    
154
    def to_json(self, na='null', show_bbox=False, drop_id=False, to_wgs84=False, **kwargs):
155
        """
156
        Export GeoDataFrame as GeoJSON string.
157
        
158
        Parameters:
159
        - na: How to handle missing values
160
        - show_bbox: Include bounding box in output
161
        - drop_id: Drop feature IDs
162
        - to_wgs84: Transform to WGS84 before export
163
        - **kwargs: Additional parameters for json.dumps
164
        
165
        Returns:
166
        - str: GeoJSON string
167
        """
168
        ...
169
    
170
    def to_wkb(self, hex=False, **kwargs):
171
        """
172
        Export geometries as Well-Known Binary.
173
        
174
        Parameters:
175
        - hex: Return hexadecimal string instead of bytes
176
        - **kwargs: Additional parameters for shapely.to_wkb
177
        
178
        Returns:
179
        - pandas.DataFrame: DataFrame with WKB geometries
180
        """
181
        ...
182
    
183
    def to_wkt(self, **kwargs):
184
        """
185
        Export geometries as Well-Known Text.
186
        
187
        Parameters:
188
        - **kwargs: Additional parameters for shapely.to_wkt
189
        
190
        Returns:
191
        - pandas.DataFrame: DataFrame with WKT geometries
192
        """
193
        ...
194
```
195

196
### Class Methods for Data Loading
197

198
Class methods available on GeoDataFrame and GeoSeries for loading data.
199

200
```python { .api }
201
class GeoDataFrame:
202
    @classmethod
203
    def from_file(cls, filename, **kwargs):
204
        """
205
        Load GeoDataFrame from geospatial file.
206
        
207
        Parameters:
208
        - filename: Path to geospatial file
209
        - **kwargs: Parameters passed to read_file
210
        
211
        Returns:
212
        - GeoDataFrame: Loaded geospatial data
213
        """
214
        ...
215
    
216
    @classmethod
217
    def from_features(cls, features, crs=None, columns=None):
218
        """
219
        Create GeoDataFrame from sequence of GeoJSON-like features.
220
        
221
        Parameters:
222
        - features: Sequence of GeoJSON feature dictionaries
223
        - crs: Coordinate reference system
224
        - columns: Column names to use
225
        
226
        Returns:
227
        - GeoDataFrame: Created from features
228
        """
229
        ...
230
    
231
    @classmethod
232
    def from_dict(cls, data, geometry=None, crs=None):
233
        """
234
        Create GeoDataFrame from dictionary.
235
        
236
        Parameters:
237
        - data: Dictionary of column data
238
        - geometry: Name of geometry column or geometry data
239
        - crs: Coordinate reference system
240
        
241
        Returns:
242
        - GeoDataFrame: Created from dictionary
243
        """
244
        ...
245
    
246
    @classmethod
247
    def from_postgis(cls, sql, con, **kwargs):
248
        """
249
        Load GeoDataFrame from PostGIS database.
250
        
251
        Parameters:
252
        - sql: SQL query or table name
253
        - con: Database connection
254
        - **kwargs: Parameters passed to read_postgis
255
        
256
        Returns:
257
        - GeoDataFrame: Loaded from database
258
        """
259
        ...
260

261
class GeoSeries:
262
    @classmethod
263
    def from_file(cls, filename, **kwargs):
264
        """
265
        Load GeoSeries from geospatial file.
266
        
267
        Parameters:
268
        - filename: Path to geospatial file
269
        - **kwargs: Parameters passed to read_file
270
        
271
        Returns:
272
        - GeoSeries: Loaded geometry data
273
        """
274
        ...
275
    
276
    @classmethod
277
    def from_wkb(cls, data, index=None, crs=None, on_invalid='raise', **kwargs):
278
        """
279
        Create GeoSeries from Well-Known Binary data.
280
        
281
        Parameters:
282
        - data: Array-like of WKB data
283
        - index: Index for resulting series
284
        - crs: Coordinate reference system
285
        - on_invalid: How to handle invalid geometries ('raise', 'warn', 'ignore')
286
        - **kwargs: Additional parameters
287
        
288
        Returns:
289
        - GeoSeries: Created from WKB data
290
        """
291
        ...
292
    
293
    @classmethod
294
    def from_wkt(cls, data, index=None, crs=None, on_invalid='raise', **kwargs):
295
        """
296
        Create GeoSeries from Well-Known Text data.
297
        
298
        Parameters:
299
        - data: Array-like of WKT data
300
        - index: Index for resulting series
301
        - crs: Coordinate reference system
302
        - on_invalid: How to handle invalid geometries ('raise', 'warn', 'ignore')
303
        - **kwargs: Additional parameters
304
        
305
        Returns:
306
        - GeoSeries: Created from WKT data
307
        """
308
        ...
309
    
310
    @classmethod
311
    def from_xy(cls, x, y, z=None, index=None, crs=None, **kwargs):
312
        """
313
        Create Point geometries from x, y coordinates.
314
        
315
        Parameters:
316
        - x: Array-like of x coordinates
317
        - y: Array-like of y coordinates
318
        - z: Array-like of z coordinates (optional)
319
        - index: Index for resulting series
320
        - crs: Coordinate reference system
321
        - **kwargs: Additional parameters
322
        
323
        Returns:
324
        - GeoSeries: Series of Point geometries
325
        """
326
        ...
327
```
328

329
## Usage Examples
330

331
### Reading Files
332

333
```python
334
import geopandas as gpd
335

336
# Read various file formats
337
gdf = gpd.read_file('data.shp')
338
gdf = gpd.read_file('data.geojson')
339
gdf = gpd.read_file('data.gpkg')
340
gdf = gpd.read_file('data.parquet')
341

342
# Read with spatial filtering
343
bbox = (-74.1, 40.6, -73.9, 40.8)  # NYC area
344
gdf = gpd.read_file('data.shp', bbox=bbox)
345

346
# Read specific rows
347
gdf = gpd.read_file('data.shp', rows=slice(0, 1000))
348

349
# Read specific columns
350
gdf = gpd.read_file('data.shp', columns=['NAME', 'POP2000', 'geometry'])
351

352
# Read from URL
353
url = 'https://example.com/data.geojson'
354
gdf = gpd.read_file(url)
355

356
# List layers in multi-layer file
357
layers = gpd.list_layers('data.gpkg')
358
print(layers)
359
```
360

361
### Writing Files
362

363
```python
364
# Write to different formats
365
gdf.to_file('output.shp')
366
gdf.to_file('output.geojson', driver='GeoJSON')
367
gdf.to_file('output.gpkg', driver='GPKG')
368

369
# Write with specific CRS
370
gdf.to_file('output.shp', crs='EPSG:4326')
371

372
# Write to Parquet with compression
373
gdf.to_parquet('output.parquet', compression='gzip')
374

375
# Export as GeoJSON string
376
geojson_str = gdf.to_json()
377

378
# Export geometries as WKT
379
wkt_df = gdf.to_wkt()
380
```
381

382
### Database Operations
383

384
```python
385
import sqlalchemy
386

387
# Read from PostGIS
388
engine = sqlalchemy.create_engine('postgresql://user:pass@host:port/db')
389

390
# Read entire table
391
gdf = gpd.read_postgis('SELECT * FROM cities', con=engine)
392

393
# Read with spatial filter
394
sql = '''
395
SELECT * FROM cities 
396
WHERE ST_Intersects(geom, ST_MakeEnvelope(-74.1, 40.6, -73.9, 40.8, 4326))
397
'''
398
gdf = gpd.read_postgis(sql, con=engine)
399

400
# Write to PostGIS
401
gdf.to_postgis('new_cities', con=engine, if_exists='replace')
402
```
403

404
### Working with Remote Data
405

406
```python
407
# Read from cloud storage with fsspec
408
gdf = gpd.read_parquet('s3://bucket/data.parquet')
409

410
# Read compressed files
411
gdf = gpd.read_file('data.zip')
412

413
# Read from web services
414
wfs_url = 'WFS:http://example.com/wfs?SERVICE=WFS&VERSION=2.0.0&REQUEST=GetCapabilities'
415
gdf = gpd.read_file(wfs_url)
416
```