v.in.ags - GRASS manual

NAME

v.in.ags - Imports vector data from an ArcGIS Server feature service.
Downloads features from an ArcGIS Server REST API endpoint \

KEYWORDS

vector, import, ArcGIS Server, REST API, OGR

SYNOPSIS

v.in.ags

v.in.ags --help

v.in.ags [-lgo] url=string [output=name] [where=string] [fields=string] [extent=string] [bbox_filter=string] [layer=integer] [spatial_rel=string] [order_by=string] [geometry_precision=integer] [max_offset=float] [download_format=string] [outsr=string] [snap=float] [datum_trans=integer] format=name [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-l: List available layers in the service and exit without importing
-g: Skip geometry; import attribute table only
-o: Override projection check (use current project's CRS); Assume that the dataset has the same CRS as the current project
--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

url=string [required]: ArcGIS Server feature layer URL; URL of the ArcGIS Server FeatureServer or MapServer layer \
output=name: Name for output vector map
where=string: SQL WHERE clause to filter features; SQL expression used to select a subset of features. \; Default: 1=1
fields=string: Comma-separated list of fields to retrieve; Attribute fields to include in the output. \; Default: *
extent=string: Output vector map extent; Options: input, region; input: extent of input data; region: extent of current computational region
bbox_filter=string: Server-side bounding box filter (xmin,ymin,xmax,ymax in WGS84); Comma-separated bounding box in geographic degrees (EPSG:4326) \
layer=integer: Layer index within the service; Zero-based layer index to use when the URL points to a \; Default: 0
spatial_rel=string: Spatial relationship used with the bounding box filter; ArcGIS Server spatial relationship constant that controls \; Options: esriSpatialRelIntersects, esriSpatialRelContains, esriSpatialRelCrosses, esriSpatialRelEnvelopeIntersects, esriSpatialRelIndexIntersects, esriSpatialRelOverlaps, esriSpatialRelTouches, esriSpatialRelWithin; Default: esriSpatialRelIntersects
order_by=string: ORDER BY fields; Comma-separated list of field names (optionally followed \
geometry_precision=integer: Number of decimal places for output coordinates; Limits coordinate precision in the downloaded data. \
max_offset=float: Maximum allowable offset for geometry generalisation; Simplification tolerance in the output spatial reference \
download_format=string: Feature download strategy; How features are fetched. auto and json read the service \; Options: auto, pbf, geojson, json; Default: auto
outsr=string: Output spatial reference (WKID) to request from the server; ArcGIS outSR well-known ID (e.g. 3358) for the downloaded \
snap=float: Snapping threshold for boundaries (map units); '-1' for no snap. Use a small positive value to fix invalid \; Default: -1
datum_trans=integer: Index number of datum transform parameters; -1 to list available datum transform parameters; Options: -1-100
format=name [required]: Output format; Options: plain, shell, json; Default: plain; plain: Human readable text output; shell: Shell script style text output; json: JSON (JavaScript Object Notation)

DESCRIPTION
NOTES
EXAMPLES
REFERENCES
SEE ALSO
AUTHORS

DESCRIPTION

v.in.ags imports vector features from an ArcGIS Server (AGS) REST API feature service or map service layer into a GRASS vector map. The module constructs the query URL automatically and imports through v.import, which reprojects the data into the current project CRS.

Download strategy

By default (download_format=auto), v.in.ags builds the /query URL and hands it to GDAL's ESRIJSON driver via v.import. GDAL reads the service directly and scrolls through all pages automatically, so no intermediate file is written. download_format=json is equivalent; download_format=geojson requests GeoJSON and uses GDAL's GeoJSON driver instead.

For large layers, download_format=pbf enables a fast path that downloads and decodes Esri Feature Buffer (PBF), a compact binary format, in-process and writes a temporary GeoJSON file for import. If PBF decoding fails at runtime the module retries the affected page with GeoJSON automatically.

Supported service types

Both FeatureServer and MapServer layer endpoints are supported, provided the layer exposes the /query operation. ArcGIS Server 10.3 or later is required for pagination; the pbf strategy requires ArcGIS Server 10.6 or ArcGIS Online.

URL formats

The url parameter accepts:

A layer URL ending with a numeric layer index:
https://host/arcgis/rest/services/Name/FeatureServer/0
A service root URL (without a layer index); in this case use the layer option to specify which layer to import:
https://host/arcgis/rest/services/Name/FeatureServer

Use the -l flag to print all available layers in a service before importing.

Inspecting a layer without importing

If output is omitted (and -l is not used), v.in.ags prints metadata for the resolved layer (id, name, geometry type, feature count, maximum record count, supported transfer formats, and field names) and exits without importing anything. This is useful for inspecting a service before committing to a download.

NOTES

Output format

The format option controls how text output is printed and applies to the -l layer listing and the layer-inspection mode described above:

plain (default): human-readable text.
shell: shell-script style output (key=value for layer info, id|type|name per line for the layer listing).
json: JSON for downstream parsing.

The format option does not affect imports; it is ignored when output is given.

Attribute filtering

The where option accepts any SQL expression supported by the ArcGIS Server being queried (SQL-92 subset). Examples:

STATE_NAME = 'California'
POP2020 > 100000
TYPE IN ('city', 'town') AND AREA_KM2 < 500

Output extent and spatial filtering

The extent option matches v.import: input (default) imports the full input, region limits the output to the current computational region. With extent=region the region is also converted to a WGS84 bounding box and used as a server-side filter, so only features overlapping the region are downloaded.

The bbox_filter option accepts an explicit bounding box xmin,ymin,xmax,ymax in geographic degrees (WGS84 / EPSG:4326), applied as a server-side spatial filter before features are downloaded. This significantly reduces transfer size for large layers.

extent and bbox_filter are mutually exclusive. The relationship between features and the bounding box (either source) is controlled by spatial_rel (default: esriSpatialRelIntersects).

Topology and snapping

Polygon layers served by ArcGIS Server frequently have invalid topology, which can import with no areas (the polygons do not appear). Use snap (in map units of the downloaded data, that is degrees for the default WGS84 download or outsr units otherwise) to snap boundary vertices so areas build. The default -1 disables snapping. As with v.import, start small (for example snap=1e-6) and increase only if areas are still missing.

Field selection

Use fields to restrict which attribute columns are retrieved. The default * retrieves all fields.

Result ordering

order_by accepts a comma-separated list of field names optionally followed by ASC or DESC, for example STATE_NAME ASC, POP2020 DESC.

Geometry options

Use geometry_precision to cap the number of coordinate decimal places returned by the server (reduces transfer size at the cost of spatial accuracy). Use max_offset to request server-side geometry generalisation; larger values produce fewer vertices.

The -g flag skips geometry entirely and imports the attribute table only.

Pagination

Pagination is automatic. In the default strategy GDAL scrolls through all pages of the service. In the pbf strategy v.in.ags reads maxRecordCount from the service metadata and issues successive resultOffset/resultRecordCount requests until all matching features have been retrieved; if that service reports supportsPagination: false, a warning is issued and only the first page is imported.

Coordinate reference system

By default data is requested from the server in WGS84 (EPSG:4326) and imported with v.import, which reprojects it into the current project CRS automatically (and imports directly, without reprojection overhead, when the project is already WGS84).

Use outsr to request a different output spatial reference (an ArcGIS outSR WKID, for example 3358). Setting outsr to the project's WKID makes the server do the reprojection, so v.import imports directly with no client-side transform. The final map is always in the project CRS regardless. outsr is ignored by the pbf strategy, which always uses EPSG:4326.

As in v.import, datum_trans selects the datum transform used during reprojection (-1 lists the available transforms), and the -o flag overrides the projection check, assuming the downloaded data already has the project's CRS (pairs well with outsr=<project WKID>).

v.in.ags -l url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized/FeatureServer

Import all features

Data is reprojected into the current project CRS automatically:

v.in.ags \
  url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized/FeatureServer/0 \
  output=usa_states

Import with an attribute filter

Import only Californian counties:

v.in.ags \
  url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_Counties_Generalized/FeatureServer/0 \
  output=california_counties \
  where="STATE_NAME = 'California'"

Import with a spatial bounding-box filter

Import features intersecting a bounding box over the US Pacific Northwest (WGS84 coordinates):

v.in.ags \
  url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized/FeatureServer/0 \
  output=pnw_states \
  bbox_filter="-125,42,-116,49"

Limit the import to the current region

extent=region filters on the server by the current region and clips the output to it:

g.region n=49 s=42 w=-125 e=-116
v.in.ags \
  url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized/FeatureServer/0 \
  output=pnw_states \
  extent=region

Fix polygon topology with snapping

If imported polygons show no areas, snap boundary vertices:

v.in.ags \
  url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized/FeatureServer/0 \
  output=usa_states \
  snap=1e-6

Change spatial relationship

Import only features completely within the bounding box:

v.in.ags \
  url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized/FeatureServer/0 \
  output=pnw_states_within \
  bbox_filter="-125,42,-116,49" \
  spatial_rel=esriSpatialRelWithin

Import with reduced precision and simplified geometry

v.in.ags \
  url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_Counties_Generalized/FeatureServer/0 \
  output=counties_simplified \
  geometry_precision=4 \
  max_offset=0.001

Import selected fields in a sorted order

v.in.ags \
  url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized/FeatureServer/0 \
  output=usa_states_slim \
  fields="STATE_NAME,STATE_ABBR,POP2020" \
  order_by="POP2020 DESC"

Request data already in the project CRS

Ask the server for the project's spatial reference (here NC State Plane, EPSG:3358) so no client-side reprojection is needed:

v.in.ags \
  url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized/FeatureServer/0 \
  output=usa_states \
  outsr=3358

Use the PBF fast path for a large layer

v.in.ags \
  url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_Counties_Generalized/FeatureServer/0 \
  output=usa_counties \
  download_format=pbf

Inspect a layer as JSON without importing

v.in.ags \
  url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized/FeatureServer/0 \
  format=json

Import attribute table only (no geometry)

v.in.ags -g \
  url=https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized/FeatureServer/0 \
  output=usa_state_attrs

Python scripting example

import grass.script as gs

gs.run_command(
    "v.in.ags",
    url="https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_States_Generalized/FeatureServer/0",
    output="usa_states",
    where="POP2020 > 1000000",
    fields="STATE_NAME,STATE_ABBR,POP2020",
    order_by="POP2020 DESC",
    download_format="auto",
    overwrite=True,
)

REFERENCES

AUTHORS

Corey T. White, NCSU GeoForAll Lab

SOURCE CODE

Available at: v.in.ags source code (history)

Latest change: Wednesday Jul 08 17:53:57 2026 in commit: 4bd2f5b678db7c31afa05c8adfdb0381e9fb5533