Skip to content

v.in.ags

Imports vector data from an ArcGIS Server feature service.

Downloads features from an ArcGIS Server REST API endpoint \

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] [--verbose] [--quiet] [--qq] [--ui]

Example:

v.in.ags url=string format=plain

grass.tools.Tools.v_in_ags(url, output=None, where="1=1", fields="*", extent=None, bbox_filter=None, layer=0, spatial_rel="esriSpatialRelIntersects", order_by=None, geometry_precision=None, max_offset=None, download_format="auto", outsr=None, snap=-1, datum_trans=None, format="plain", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.v_in_ags(url="string", format="json")

This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

grass.script.parse_command("v.in.ags", url, output=None, where="1=1", fields="*", extent=None, bbox_filter=None, layer=0, spatial_rel="esriSpatialRelIntersects", order_by=None, geometry_precision=None, max_offset=None, download_format="auto", outsr=None, snap=-1, datum_trans=None, format="plain", flags=None, overwrite=None, verbose=None, quiet=None, superquiet=None)

Example:

gs.parse_command("v.in.ags", url="string", format="json")

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
    Allowed values: 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 \
    Allowed values: 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 \
    Allowed values: 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
    Allowed values: -1-100
format=name [required]
    Output format
    Allowed values: plain, shell, json
    Default: plain
    plain: Human readable text output
    shell: Shell script style text output
    json: JSON (JavaScript Object Notation)
-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
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

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

Returns:

result : grass.tools.support.ToolResult | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned.

Raises:

grass.tools.ToolError: When the tool ended with an error.

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

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>).

Temporary files

Only the pbf strategy writes a temporary GeoJSON file (in the system temporary directory, removed automatically on exit). The default strategy streams the service through GDAL and creates no temporary file.

EXAMPLES

List layers available in a service

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

SEE ALSO

v.import, v.in.ogr, v.in.wfs, v.proj

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 4bd2f5b