Esri JSON — ArcGIS REST API Format for Enterprise GIS Workflows

2026-06-2013 min read

Esri JSONArcGIS RESTArcGIS Onlinefeature serviceenterprise GIS

Export formats: ESRI-JSON

Esri JSON is a feature serialization format that became the standard output of the ArcGIS REST API back in 2008, long before GeoJSON.org formalized as RFC 7946. It is effectively a proprietary competitor to GeoJSON that has existed in parallel and dominates enterprise GIS workflows wherever the Esri ecosystem operates: ArcGIS Online, ArcGIS Enterprise, ArcGIS JavaScript API, Survey123, Dashboards, Web AppBuilder. Unlike GeoJSON, the Esri JSON specification is owned and controlled by Esri, and it covers significantly more functionality: native support for raster, network analysis, geometry server operations, symbology, web map persistence. For teams working in the ArcGIS stack, Esri JSON is the lingua franca that every component speaks. On osm2cdr.ru esri_json_exporter.py takes a bbox and generates Esri JSON ready to upload to ArcGIS Online as a hosted feature layer or to import into ArcGIS Pro as a source.

Map generation of Dubai city center

History: ArcGIS Server REST API 2007 → Esri JSON spec → ArcGIS Online

Esri (Environmental Systems Research Institute) was founded in 1969 by Jack and Laura Dangermond in Redlands, California. By the 2000s it had become the undisputed commercial leader of the GIS industry. In September 2007, Esri released ArcGIS Server 9.3, and with it came the ArcGIS REST API — an HTTP interface for server operations (query, identify, find, geocode, route, geometry transform). This was a key architectural pivot: instead of heavy SOAP web services that required WSDL-generated client code, REST offered simple URL endpoints with JSON output. The Esri JSON spec formalized over 2008–2009 as part of the REST API documentation — initially as a pragmatic engineering decision rather than a standalone standard.

In parallel, GeoJSON was taking shape in the open-source community. The first draft specification appeared in 2008, led by Howard Butler and Sean Gillies among others. GeoJSON existed as a community spec without formal status for a long time. Only in August 2016 did the IETF publish RFC 7946 — the final GeoJSON specification as an Internet Standard. By that point Esri JSON was already deployed across tens of thousands of enterprise installations and had become the backbone of ArcGIS Online (the Esri SaaS platform launched in 2012).

ArcGIS Online brought with it the web map specification — a JSON format describing a complete web map: basemap, operational layers, popups, time settings, bookmarks. Web map JSON is stored as a webmap.json Portal item, with its spec maintained in the open Esri/web-map-specification repository on GitHub. This is a rare case of open Esri documentation. The ArcGIS Server line (from 9.0 in 2004 to ArcGIS Enterprise 11.0 in 2022) served enterprise deployments from municipalities to federal agencies; today Esri JSON is the standard response format for any REST endpoint: feature service /query, image service /exportImage, geocode /findAddressCandidates, network analysis /solveRoute.

Inside Esri JSON: geometry, attributes, spatialReference

Esri JSON is a text-based JSON format with UTF-8 encoding. Unlike GeoJSON, it lacks a hard FeatureCollection-style wrapper, and the top-level structure depends on the REST endpoint that returned it. A typical response from a feature service /query?outFormat=json looks like:

{
  "objectIdFieldName": "OBJECTID",
  "geometryType": "esriGeometryPoint",
  "spatialReference": { "wkid": 4326 },
  "fields": [
    { "name": "OBJECTID", "type": "esriFieldTypeOID" },
    { "name": "Name", "type": "esriFieldTypeString", "alias": "Place Name" }
  ],
  "features": [
    {
      "geometry": { "x": 37.6173, "y": 55.7558, "spatialReference": { "wkid": 4326 } },
      "attributes": { "OBJECTID": 1, "Name": "Moscow" }
    }
  ]
}

Geometry types. Esri JSON defines four primary geometry types: esriGeometryPoint ({ x, y, z?, m?, spatialReference }), esriGeometryMultipoint ({ points: [[x,y]], spatialReference }), esriGeometryPolyline ({ paths: [[[x,y]]], spatialReference }), esriGeometryPolygon ({ rings: [[[x,y]]], spatialReference }). Each geometry object is self-contained — carries its own spatialReference, which in theory allows mixed-CRS feature collections (rare in practice).

Ring orientation — the main pitfall. Esri JSON polygons use the opposite convention to GeoJSON: outer rings are clockwise, inner rings (holes) counter-clockwise. GeoJSON RFC 7946 prescribes counter-clockwise outer (right-hand rule) and clockwise inner. Converting between formats without reversing vertex order produces inverted polygons — a bug that has surfaced for years in ArcGIS-to-OSS pipelines. ogr2ogr and the GDAL ESRIJSON driver handle this automatically; hand-written converters frequently miss it.

Attributes — typed schema. Unlike GeoJSON's properties (free-form JSON object), Esri JSON attributes is a nested object with a typed schema described in the top-level fields array. Each field has name, type (esriFieldTypeOID, esriFieldTypeString, esriFieldTypeInteger, esriFieldTypeDouble, esriFieldTypeDate, esriFieldTypeGUID, esriFieldTypeGlobalID, etc.), optional alias (display name in UI), length for string fields, domain (coded values or range constraint). This lets downstream tools type columns correctly without heuristics.

spatialReference — WKID-based. Esri uses its own coordinate system identifier — wkid (Well-Known ID), which in most cases matches EPSG codes but not always. The canonical example: WKID 102100 (Web Mercator Auxiliary Sphere — an Esri-specific Web Mercator variant with custom transformation parameters), which is effectively equivalent to EPSG:3857, but Esri tooling has historically preferred 102100. Modern Esri JSON often contains a fully-qualified { "wkid": 102100, "latestWkid": 3857 } object that helps both camps interpret the CRS correctly. For WGS84 geographic, { "wkid": 4326 } is used.

M and Z coordinates. Esri JSON supports 3D and linear referencing through optional Z (elevation) and M (measure) values. The top-level geometry declares hasZ: true / hasM: true, and vertex arrays extend to [x, y, z, m]. Used in Linear Referencing Systems (miles along a highway), 3D Scene Services, hydrology networks.

drawingInfo — symbology in JSON. A unique Esri JSON extension over GeoJSON. A layer-level response can include a drawingInfo object describing complete symbology: renderer (simple, classBreaks, uniqueValue, heatmap), transparency, labelingInfo, scale-dependent visibility. This makes Esri JSON self-contained for rendering — the client gets not only the data but also rendering instructions.

Use cases: ArcGIS Online, JavaScript API, feature services, Survey123

ArcGIS Online Web Maps. The central use case. A web map in ArcGIS Online is a Portal item with a JSON payload describing basemap, operational layers (each linking to a feature service URL), popups, time settings, bookmarks. Web map JSON is loaded by ArcGIS JavaScript API, Field Maps, Collector, Survey123, Dashboards — the same JSON drives dozens of platforms. This is the foundational value of the Esri ecosystem.

Enterprise feature services. When an organization publishes a hosted feature layer (via ArcGIS Pro «Share As Web Layer» or the ArcGIS Online uploader), the server exposes a REST endpoint like https://services.arcgis.com/.../FeatureServer/0. Any request to /query?where=...&outFormat=json returns Esri JSON. Used by ETL pipelines (FME), CRM/ERP integrations, BI tools (Power BI has a native ArcGIS connector).

ArcGIS JavaScript API 4.x. Modern ArcGIS JS API (4.x, released 2016, replacing the Dojo-based 3.x) uses Esri JSON for all data exchange. FeatureLayer loads from a feature service, filters through a Query object, returns results as a FeatureSet.

Survey123, Dashboards, Field Maps. Survey123 is Esri's mobile data-collection app; every form submission converts to an Esri JSON feature through applyEdits. Dashboards — operational widgets (gauge, indicator, list), real-time updates via polling Esri JSON. Field Maps — offline-first mobile mapping with local SQLite ↔ Esri JSON sync. Web AppBuilder and Experience Builder are no-code builders; the data source is always Esri JSON through a feature service. Federation between all these tools is the main value of the format.

Map generation of Vienna city center

Software / tools support

Esri native stack. ArcGIS Pro (flagship desktop, replaced ArcMap in 2015) fully supports Esri JSON for import/export and publishing. ArcMap (legacy, EOL March 2026) — through extensions. ArcGIS JavaScript API 4.x (native), 3.x (deprecated). ArcGIS API for Python (pip install arcgis) — Esri-official library; the FeatureSet class serializes Esri JSON. ArcGIS API for Flex and Silverlight — both deprecated.

Third-party tools. QGIS — read feature services through built-in ArcGISFeatureServer data source. GeoServer and MapServer — their GetFeature endpoints output WFS XML or GeoJSON (Esri JSON output only via community plugins). ogr2ogr supports Esri JSON through the ESRIJSON driver: ogr2ogr -f "ESRIJSON" output.json input.shp, -oo FEATURE_SERVER_PAGING=YES for bulk querying. GDAL ESRIJSON driver — read/write added in GDAL 2.x. FME (Safe Software) — premier integration tool through ArcGIS Online Reader/Writer.

Languages. Python: arcgis (Esri-official), arcgis2geojson (community converter). JavaScript: ArcGIS JS API, terraformer-arcgis-parser (Esri-developed converter Esri JSON ↔ GeoJSON, MIT license). R: arcgisbinding, arcgislayers.

Esri JSON vs GeoJSON: key differences

These two formats are often compared since both are JSON-based vector serialization. But there are substantial differences that matter in real pipelines.

Ring orientation. Esri polygons — outer clockwise, inner counter-clockwise. GeoJSON — the opposite (RFC 7946 §3.1.6): outer counter-clockwise (right-hand rule), inner clockwise. Conversion requires reversing vertex arrays for each ring. This is the most frequent source of bugs in hand-written conversion.

spatialReference. Esri uses a WKID-based object ({ wkid: 4326 } or { wkid: 102100, latestWkid: 3857 }). GeoJSON RFC 7946 strictly mandates WGS84 (EPSG:4326) and prohibits custom CRS (the 2008 draft spec allowed it through a crs member, but RFC 7946 dropped it). If data is not in WGS84, RFC 7946 requires reprojection before export. Esri JSON allows any CRS without reprojection.

Top-level wrapper. Esri JSON for a feature service returns { features: [...], fields: [...], geometryType: ..., spatialReference: ... } — features directly in a top-level array. GeoJSON wraps in FeatureCollection: { type: "FeatureCollection", features: [...] }. Each Esri feature lacks a type discriminator, whereas a GeoJSON Feature is { type: "Feature", geometry: ..., properties: ... }.

Attributes vs properties. Esri: attributes: { fieldName: value } — typed through the fields schema. GeoJSON: properties: { ... } — untyped free-form JSON, schema implicit.

Encoding and compression. Both UTF-8. Esri JSON over the REST API supports PBF (Protocol Buffers) output for compression — outFormat=pbf — which significantly reduces payload size for large feature sets. GeoJSON offers nothing comparable, though topojson exists as a separate format.

Spec ownership. GeoJSON — open IETF standard, modification through RFC process, anyone can implement without licensing. Esri JSON — proprietary spec under Esri control, documented in REST API reference, no formal IETF/ISO process, but de-facto stable thanks to deployment scale.

Practical takeaway. For web distribution and open-source projects — GeoJSON. For ingestion into ArcGIS Online or working with feature services — Esri JSON. Bidirectional conversion exists but should go through tested tools (terraformer-arcgis-parser, ogr2ogr), not hand-written scripts.

OSM2CDR workflow: Esri JSON for ArcGIS ingestion

Our esri_json_exporter.py takes a bbox of an OSM area and generates an Esri JSON feature collection ready to upload to ArcGIS Online as a hosted feature layer or to import into ArcGIS Pro as a source.

Step 1: Load OSM features. PostGIS query through local_osm_loader.py for a bbox filtering by selected layers (roads, buildings, water, POI, landuse, boundaries). For each feature we extract geometry in WKB binary and attributes from OSM tags.

Step 2: Geometry conversion. WKB → Esri geometry representation. Point → { x, y, spatialReference: { wkid: 4326 } }. LineString → { paths: [[[lon, lat]]] }. Polygon → { rings: [[[lon, lat]]] } with vertex order reversal to match Esri's clockwise outer convention (since PostGIS returns counter-clockwise per OGC spec). MultiPolygon → multiple rings in a single Esri polygon. MultiLineString → multiple paths in a single Esri polyline.

Step 3: Attributes mapping. OSM tags → Esri attributes. Since OSM tags are free-form key=value, we flatten any nested structures and normalize field names (Esri requires field names ≤10 chars for shapefile compatibility, ≤64 for feature services). name, name:en, addr:street, highway, building become separate fields. Types are heuristically determined: numeric strings → esriFieldTypeInteger or esriFieldTypeDouble, everything else → esriFieldTypeString.

Step 4: Schema generation. The top-level fields array describes the schema: OBJECTID (auto-generated, esriFieldTypeOID), then all user attributes. geometryType is set to esriGeometryPoint, esriGeometryPolyline, or esriGeometryPolygon depending on the dominant geometry in the collection (for mixed-geometry exports we split into separate files).

Step 5: spatialReference. By default { wkid: 4326 } (WGS84) for compatibility. If the user selects a non-WGS84 CRS through CRSManager — soft reprojection through PostGIS ST_Transform, and the corresponding WKID is written into spatialReference.

Step 6: Serialize. JSON output is written through a streaming JSON writer (ijson library) to prevent OOM on large exports. Output — a single .json file, typical size 500KB–50MB for an urban bbox.

Limitations of our export. We generate static Esri JSON, not a full feature service response. That means: no objectIdFieldName query parameter handling, no paging support, no applyEdits capability. Output is intended for one-time ingestion into ArcGIS Online — the user imports the JSON through «Add Item → From your computer» in the ArcGIS Online portal, which creates a hosted feature layer. Alternatively — open in ArcGIS Pro through «Add Data → JSON». Nested attributes in OSM (theoretically possible through relations with member roles) are flattened to plain key=value pairs, simplifying the schema but losing some semantics. For production federation workflows, we recommend publishing the output as a hosted feature layer and working through the generated feature service URL.

Compatibility with the GeoJSON pipeline. Since Esri JSON and GeoJSON convert bidirectionally through terraformer-arcgis-parser or ogr2ogr, our export can fit into mixed pipelines: osm2cdr → Esri JSON → ArcGIS Online → Power BI dashboard, or osm2cdr → Esri JSON → ogr2ogr → GeoJSON for a web map.

Map generation of Istanbul city center

Conclusion

Esri JSON is «GeoJSON for enterprise GIS»: the same fundamental approach (JSON serialization of vector features) but with typed schema, native WKID CRS support, drawingInfo, M/Z coordinates, and integration with the entire ArcGIS ecosystem. The specification belongs to Esri and evolves in sync with the REST API, ensuring long-term stability but limiting open governance. For teams whose mapping workflow is built on ArcGIS Online, ArcGIS Pro, Field Maps, Survey123, Dashboards — Esri JSON is the lingua franca that every component speaks. For teams on an open-source GIS stack — GeoJSON remains the right choice, and Esri JSON is needed only for ingestion points into enterprise customer environments.

On osm2cdr.ru, Esri JSON export through /api/render with format esri-json produces JSON ready to upload to ArcGIS Online as a hosted feature layer or to import into ArcGIS Pro. It's a convenient shortcut for users who need OSM data inside an ArcGIS workflow without intermediate conversion through QGIS or ogr2ogr.

Try exporting OSM to Esri JSON for your city and upload the result to ArcGIS Online through «Add Item → From your computer».

Sources

ArcGIS REST API documentation (Esri) — developers.arcgis.com/rest/services-reference
ArcGIS Web Map Specification — github.com/Esri/web-map-specification
GeoJSON RFC 7946 (IETF, August 2016) — datatracker.ietf.org/doc/html/rfc7946
terraformer-arcgis-parser (Esri, MIT license) — github.com/Esri/terraformer-arcgis-parser
GDAL ESRIJSON driver documentation — gdal.org/drivers/vector/esrijson.html