restgdf¶
Lightweight async Esri REST client with optional GeoPandas extras.
restgdf is an async-first wrapper around Esri/ArcGIS REST Feature and Map
services. The base install gives you typed metadata/query helpers, raw feature
rows, crawl/auth utilities, and validated pydantic models for every response.
Install restgdf[geo] when you want geopandas.GeoDataFrame and
pandas-backed helpers on top of that light-core surface.
pip install restgdf
pip install "restgdf[geo]"
Planning a 2.x → 3.x rollout? Treat the split above as the stable dependency
boundary: geo-enabled environments should depend on restgdf[geo]
explicitly. See restgdf migration guide for the upcoming optional-dependency notes
and the preserved 1.x → 2.0 guide.
GeoDataFrame workflow (requires restgdf[geo]):
import asyncio
from aiohttp import ClientSession
from restgdf import FeatureLayer
url = "https://maps1.vcgov.org/arcgis/rest/services/Beaches/MapServer/6"
async def main():
async with ClientSession() as session:
layer = await FeatureLayer.from_url(url, session=session)
return await layer.get_gdf()
gdf = asyncio.run(main())
Explore the docs¶
Install, connect to a FeatureServer, and choose between raw-row and GeoDataFrame workflows.
Pass ArcGIS tokens directly or let ArcGISTokenSession mint and refresh them for you.
Every ArcGIS response is a typed BaseModel — LayerMetadata, FeaturesResponse, CrawlReport, and more.
FeatureLayer, Directory, ArcGISTokenSession, and the migration helpers in restgdf.compat.
Low-level crawl, HTTP, token, raw-record, and GeoDataFrame helpers.
Compose streaming primitives into dict, DataFrame, or GeoDataFrame shapes.
Layered config with RESTGDF_* env vars, frozen sub-configs, and sensible defaults.
Automatic retry, exponential back-off, and per-service-root rate limiting.
OpenTelemetry spans, log correlation, and RestgdfInstrumentor.
Exception hierarchy, structured attributes, and recovery patterns.
The upcoming 3.x geo-extra change and the preserved 1.x → 2.0 rewrite table live here.
Every page is also published as plain Markdown (append .md to any URL),
plus llms.txt / llms-full.txt indexes for RAG pipelines and coding agents.