0
# Geospatial Operations
1

2
Geometric processing, spatial analysis, and interactive mapping capabilities. This module supports conversion between DataFrame and GeoDataFrame formats, spatial operations, and creation of interactive maps using Folium.
3

4
## Data Access with Geometry
5

6
### Routes with Geometry
7

8
```python { .api }
9
def get_routes(feed, date=None, time=None, *, as_gdf=False, use_utm=False, split_directions=False):
10
    """
11
    Get routes DataFrame or GeoDataFrame with optional geometry.
12
    
13
    Parameters:
14
    - feed (Feed): GTFS feed object
15
    - date (str, optional): Filter by service date (YYYYMMDD)
16
    - time (str, optional): Filter by active time (HH:MM:SS)
17
    - as_gdf (bool): Return as GeoDataFrame with geometry
18
    - use_utm (bool): Use UTM projection for geometry
19
    - split_directions (bool): Split routes by direction
20
    
21
    Returns:
22
    - DataFrame or GeoDataFrame: Routes data with optional geometry
23
    """
24
```
25

26
### Stops with Geometry
27

28
```python { .api }
29
def get_stops(feed, date=None, trip_ids=None, route_ids=None, *, in_stations=False, as_gdf=False, use_utm=False):
30
    """
31
    Get stops DataFrame or GeoDataFrame with optional geometry.
32
    
33
    Parameters:
34
    - feed (Feed): GTFS feed object
35
    - date (str, optional): Filter by service date (YYYYMMDD)
36
    - trip_ids (list, optional): Filter by trip IDs
37
    - route_ids (list, optional): Filter by route IDs
38
    - in_stations (bool): Include stops within stations
39
    - as_gdf (bool): Return as GeoDataFrame with geometry
40
    - use_utm (bool): Use UTM projection for geometry
41
    
42
    Returns:
43
    - DataFrame or GeoDataFrame: Stops data with optional geometry
44
    """
45

46
def geometrize_stops(stops, *, use_utm=False):
47
    """
48
    Convert stops DataFrame to GeoDataFrame.
49
    
50
    Parameters:
51
    - stops (DataFrame): Stops DataFrame
52
    - use_utm (bool): Use UTM projection
53
    
54
    Returns:
55
    - GeoDataFrame: Stops with Point geometry
56
    """
57

58
def ungeometrize_stops(stops_g):
59
    """
60
    Convert stops GeoDataFrame back to DataFrame.
61
    
62
    Parameters:
63
    - stops_g (GeoDataFrame): Stops GeoDataFrame
64
    
65
    Returns:
66
    - DataFrame: Stops DataFrame without geometry
67
    """
68
```
69

70
### Shapes with Geometry
71

72
```python { .api }
73
def get_shapes(feed, *, as_gdf=False, use_utm=False):
74
    """
75
    Get shapes DataFrame or GeoDataFrame with optional geometry.
76
    
77
    Parameters:
78
    - feed (Feed): GTFS feed object
79
    - as_gdf (bool): Return as GeoDataFrame with geometry
80
    - use_utm (bool): Use UTM projection for geometry
81
    
82
    Returns:
83
    - DataFrame or GeoDataFrame: Shapes data with optional geometry
84
    """
85

86
def geometrize_shapes(shapes, *, use_utm=False):
87
    """
88
    Convert shapes DataFrame to GeoDataFrame with LineString geometry.
89
    
90
    Parameters:
91
    - shapes (DataFrame): Shapes DataFrame
92
    - use_utm (bool): Use UTM projection
93
    
94
    Returns:
95
    - GeoDataFrame: Shapes with LineString geometry
96
    """
97

98
def ungeometrize_shapes(shapes_g):
99
    """
100
    Convert shapes GeoDataFrame back to DataFrame.
101
    
102
    Parameters:
103
    - shapes_g (GeoDataFrame): Shapes GeoDataFrame
104
    
105
    Returns:
106
    - DataFrame: Shapes DataFrame without geometry
107
    """
108

109
def append_dist_to_shapes(feed):
110
    """
111
    Calculate and append shape_dist_traveled field to shapes.
112
    
113
    Parameters:
114
    - feed (Feed): GTFS feed object (modified in-place)
115
    
116
    Returns:
117
    - Feed: Feed with updated shapes
118
    """
119
```
120

121
### Trips with Geometry
122

123
```python { .api }
124
def get_trips(feed, date=None, time=None, *, as_gdf=False, use_utm=False):
125
    """
126
    Get trips DataFrame or GeoDataFrame with optional geometry.
127
    
128
    Parameters:
129
    - feed (Feed): GTFS feed object
130
    - date (str, optional): Filter by service date (YYYYMMDD)
131
    - time (str, optional): Filter by active time (HH:MM:SS)
132
    - as_gdf (bool): Return as GeoDataFrame with geometry
133
    - use_utm (bool): Use UTM projection for geometry
134
    
135
    Returns:
136
    - DataFrame or GeoDataFrame: Trips data with optional geometry
137
    """
138
```
139

140
### Stop Times with Geometry
141

142
```python { .api }
143
def get_stop_times(feed, date=None):
144
    """
145
    Get stop times DataFrame, optionally filtered by date.
146
    
147
    Parameters:
148
    - feed (Feed): GTFS feed object
149
    - date (str, optional): Filter by service date (YYYYMMDD)
150
    
151
    Returns:
152
    - DataFrame: Stop times data
153
    """
154

155
def append_dist_to_stop_times(feed):
156
    """
157
    Calculate and append shape_dist_traveled to stop_times.
158
    
159
    Parameters:
160
    - feed (Feed): GTFS feed object (modified in-place)
161
    
162
    Returns:
163
    - Feed: Feed with updated stop_times
164
    """
165

166
def get_start_and_end_times(feed, date=None):
167
    """
168
    Get earliest and latest times in stop_times.
169
    
170
    Parameters:
171
    - feed (Feed): GTFS feed object
172
    - date (str, optional): Filter by service date
173
    
174
    Returns:
175
    - list: [start_time, end_time] in HH:MM:SS format
176
    """
177
```
178

179
## Spatial Analysis
180

181
### Geometric Utilities
182

183
```python { .api }
184
def build_geometry_by_shape(feed, shape_ids=None, *, use_utm=False):
185
    """
186
    Build dictionary mapping shape IDs to geometry objects.
187
    
188
    Parameters:
189
    - feed (Feed): GTFS feed object
190
    - shape_ids (list, optional): Specific shape IDs to process
191
    - use_utm (bool): Use UTM projection
192
    
193
    Returns:
194
    - dict: Shape ID to geometry mapping
195
    """
196

197
def build_geometry_by_stop(feed, stop_ids=None, *, use_utm=False):
198
    """
199
    Build dictionary mapping stop IDs to geometry objects.
200
    
201
    Parameters:
202
    - feed (Feed): GTFS feed object
203
    - stop_ids (list, optional): Specific stop IDs to process
204
    - use_utm (bool): Use UTM projection
205
    
206
    Returns:
207
    - dict: Stop ID to geometry mapping
208
    """
209

210
def split_simple(shapes_g, segmentize_m=5):
211
    """
212
    Split non-simple LineStrings into simple sub-LineStrings.
213
    
214
    Parameters:
215
    - shapes_g (GeoDataFrame): Shapes GeoDataFrame
216
    - segmentize_m (float): Segmentization distance in meters
217
    
218
    Returns:
219
    - GeoDataFrame: Shapes with simple LineStrings
220
    """
221
```
222

223
### Spatial Queries
224

225
```python { .api }
226
def get_shapes_intersecting_geometry(feed, geometry, shapes_g=None, *, as_gdf=False):
227
    """
228
    Get shapes that intersect with a given geometry.
229
    
230
    Parameters:
231
    - feed (Feed): GTFS feed object
232
    - geometry: Shapely geometry object
233
    - shapes_g (GeoDataFrame, optional): Pre-computed shapes GeoDataFrame
234
    - as_gdf (bool): Return as GeoDataFrame
235
    
236
    Returns:
237
    - DataFrame or GeoDataFrame: Intersecting shapes
238
    """
239

240
def get_stops_in_area(feed, area):
241
    """
242
    Get stops within a given area (GeoDataFrame).
243
    
244
    Parameters:
245
    - feed (Feed): GTFS feed object
246
    - area (GeoDataFrame): Area geometry to query within
247
    
248
    Returns:
249
    - DataFrame: Stops within the specified area
250
    """
251

252
def compute_bounds(feed, stop_ids=None):
253
    """
254
    Compute bounding box of stops.
255
    
256
    Parameters:
257
    - feed (Feed): GTFS feed object
258
    - stop_ids (list, optional): Specific stop IDs to bound
259
    
260
    Returns:
261
    - ndarray: Bounding box coordinates [min_lon, min_lat, max_lon, max_lat]
262
    """
263

264
def compute_convex_hull(feed, stop_ids=None):
265
    """
266
    Compute convex hull of stops.
267
    
268
    Parameters:
269
    - feed (Feed): GTFS feed object
270
    - stop_ids (list, optional): Specific stop IDs to hull
271
    
272
    Returns:
273
    - Polygon: Shapely Polygon representing convex hull
274
    """
275

276
def compute_centroid(feed, stop_ids=None):
277
    """
278
    Compute centroid of stops.
279
    
280
    Parameters:
281
    - feed (Feed): GTFS feed object
282
    - stop_ids (list, optional): Specific stop IDs to center
283
    
284
    Returns:
285
    - Point: Shapely Point representing centroid
286
    """
287

288
def compute_screen_line_counts(feed, screen_lines, dates, segmentize_m=5, *, include_testing_cols=False):
289
    """
290
    Count transit trips crossing screen lines.
291
    
292
    Parameters:
293
    - feed (Feed): GTFS feed object  
294
    - screen_lines: Screen line geometries
295
    - dates (list): List of dates to analyze
296
    - segmentize_m (float): Segmentization distance in meters
297
    - include_testing_cols (bool): Include debugging columns
298
    
299
    Returns:
300
    - DataFrame: Screen line crossing counts
301
    """
302
```
303

304
def get_stops_in_area(feed, area):
305
    """
306
    Get stops within a polygon area.
307
    
308
    Parameters:
309
    - feed (Feed): GTFS feed object
310
    - area: Shapely Polygon or MultiPolygon
311
    
312
    Returns:
313
    - DataFrame: Stops within the area
314
    """
315
```
316
317
### Geometric Calculations
318

319
```python { .api }
320
def compute_bounds(feed, stop_ids=None):
321
    """
322
    Compute bounding box of stops.
323
    
324
    Parameters:
325
    - feed (Feed): GTFS feed object
326
    - stop_ids (list, optional): Specific stop IDs
327
    
328
    Returns:
329
    - tuple: (min_lon, min_lat, max_lon, max_lat)
330
    """
331

332
def compute_convex_hull(feed, stop_ids=None):
333
    """
334
    Compute convex hull of stops.
335
    
336
    Parameters:
337
    - feed (Feed): GTFS feed object
338
    - stop_ids (list, optional): Specific stop IDs
339
    
340
    Returns:
341
    - Polygon: Convex hull geometry
342
    """
343

344
def compute_centroid(feed, stop_ids=None):
345
    """
346
    Compute centroid of stops.
347
    
348
    Parameters:
349
    - feed (Feed): GTFS feed object
350
    - stop_ids (list, optional): Specific stop IDs
351
    
352
    Returns:
353
    - Point: Centroid geometry
354
    """
355
```
356

357
## Data Export
358

359
### GeoJSON Export
360

361
```python { .api }
362
def routes_to_geojson(feed, route_ids=None, *, split_directions=False, include_stops=False):
363
    """
364
    Convert routes to GeoJSON format.
365
    
366
    Parameters:
367
    - feed (Feed): GTFS feed object
368
    - route_ids (list, optional): Specific route IDs to export
369
    - split_directions (bool): Split routes by direction
370
    - include_stops (bool): Include stop points in output
371
    
372
    Returns:
373
    - dict: GeoJSON FeatureCollection
374
    """
375

376
def stops_to_geojson(feed, stop_ids=None):
377
    """
378
    Convert stops to GeoJSON format.
379
    
380
    Parameters:
381
    - feed (Feed): GTFS feed object
382
    - stop_ids (list, optional): Specific stop IDs to export
383
    
384
    Returns:
385
    - dict: GeoJSON FeatureCollection
386
    """
387

388
def shapes_to_geojson(feed, shape_ids=None):
389
    """
390
    Convert shapes to GeoJSON format.
391
    
392
    Parameters:
393
    - feed (Feed): GTFS feed object
394
    - shape_ids (list, optional): Specific shape IDs to export
395
    
396
    Returns:
397
    - dict: GeoJSON FeatureCollection
398
    """
399

400
def trips_to_geojson(feed, trip_ids=None, *, include_stops=False):
401
    """
402
    Convert trips to GeoJSON format.
403
    
404
    Parameters:
405
    - feed (Feed): GTFS feed object
406
    - trip_ids (list, optional): Specific trip IDs to export
407
    - include_stops (bool): Include stop points in output
408
    
409
    Returns:
410
    - dict: GeoJSON FeatureCollection
411
    """
412

413
def stop_times_to_geojson(feed, trip_ids=None):
414
    """
415
    Convert stop times to GeoJSON points.
416
    
417
    Parameters:
418
    - feed (Feed): GTFS feed object
419
    - trip_ids (list, optional): Specific trip IDs to export
420
    
421
    Returns:
422
    - dict: GeoJSON FeatureCollection
423
    """
424
```
425

426
## Interactive Mapping
427

428
### Route Mapping
429

430
```python { .api }
431
def map_routes(feed, route_ids=None, route_short_names=None, color_palette=COLORS_SET2, *, show_stops=False):
432
    """
433
    Create Folium map displaying routes.
434
    
435
    Parameters:
436
    - feed (Feed): GTFS feed object
437
    - route_ids (list, optional): Specific route IDs to display
438
    - route_short_names (list, optional): Route short names to display
439
    - color_palette (list): Colors for route visualization
440
    - show_stops (bool): Include stops on the map
441
    
442
    Returns:
443
    - folium.Map: Interactive map with routes
444
    """
445
```
446

447
### Stop Mapping
448

449
```python { .api }
450
def map_stops(feed, stop_ids, stop_style=STOP_STYLE):
451
    """
452
    Create Folium map displaying stops.
453
    
454
    Parameters:
455
    - feed (Feed): GTFS feed object
456
    - stop_ids (list): Stop IDs to display
457
    - stop_style (dict): Leaflet circleMarker style parameters
458
    
459
    Returns:
460
    - folium.Map: Interactive map with stops
461
    """
462

463
def map_trips(feed, trip_ids, color_palette=COLORS_SET2, *, show_stops=False, show_direction=False):
464
    """
465
    Create Folium map displaying trips.
466
    
467
    Parameters:
468
    - feed (Feed): GTFS feed object
469
    - trip_ids (list): Trip IDs to display  
470
    - color_palette (list): Colors for trip visualization
471
    - show_stops (bool): Include stops on the map
472
    - show_direction (bool): Show trip direction arrows
473
    
474
    Returns:
475
    - folium.Map: Interactive map with trips
476
    """
477
```
478

479
These mapping functions create interactive Folium maps for visualizing GTFS data with customizable styling and display options.
480

481
## Usage Examples
482

483
### Basic Geospatial Operations
484

485
```python
486
import gtfs_kit as gk
487

488
# Load feed
489
feed = gk.read_feed('gtfs.zip', dist_units='km')
490

491
# Get routes as GeoDataFrame
492
routes_gdf = gk.get_routes(feed, as_gdf=True)
493

494
# Get stops with UTM projection
495
stops_gdf = gk.get_stops(feed, as_gdf=True, use_utm=True)
496

497
# Get shapes with geometry
498
shapes_gdf = gk.get_shapes(feed, as_gdf=True)
499
```
500

501
### Spatial Analysis
502

503
```python
504
# Compute feed boundaries
505
bounds = gk.compute_bounds(feed)
506
hull = gk.compute_convex_hull(feed)
507
center = gk.compute_centroid(feed)
508

509
# Find shapes intersecting an area
510
from shapely.geometry import Polygon
511
area = Polygon([(lon1, lat1), (lon2, lat2), (lon3, lat3), (lon4, lat4)])
512
intersecting_shapes = gk.get_shapes_intersecting_geometry(feed, area, as_gdf=True)
513

514
# Get stops in area
515
stops_in_area = gk.get_stops_in_area(feed, area)
516
```
517

518
### Export and Visualization
519

520
```python
521
# Export to GeoJSON
522
routes_geojson = gk.routes_to_geojson(feed, split_directions=True)
523
stops_geojson = gk.stops_to_geojson(feed)
524

525
# Create interactive maps
526
route_map = gk.map_routes(feed, route_ids=['route_1', 'route_2'], show_stops=True)
527
stop_map = gk.map_stops(feed, stop_ids=['stop_1', 'stop_2'])
528

529
# Save maps to HTML
530
route_map.save('routes.html')
531
stop_map.save('stops.html')
532
```
533

534
The geospatial capabilities enable comprehensive spatial analysis and visualization of transit networks, supporting both analytical workflows and interactive exploration of GTFS data.