v.what
Queries a vector map at given locations.
v.what [-aidgjm] map=name [,name,...] [layer=string [,string,...]] [type=string [,string,...]] coordinates=east,north [distance=float] [columns=name [,name,...]] [format=name] [--verbose] [--quiet] [--qq] [--ui]
Example:
v.what map=name coordinates=0.0
grass.script.parse_command("v.what", map, layer="-1", type="point,line,area,face", coordinates, distance=0, columns=None, format=None, flags=None, verbose=None, quiet=None, superquiet=None)
Example:
gs.parse_command("v.what", map="name", coordinates=0.0, format="json")
grass.tools.Tools.v_what(map, layer="-1", type="point,line,area,face", coordinates, distance=0, columns=None, format=None, flags=None, verbose=None, quiet=None, superquiet=None)
Example:
tools = Tools()
tools.v_what(map="name", coordinates=0.0, format="json")
This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.
Parameters
map=name [,name,...] [required]
Name of vector map(s)
layer=string [,string,...]
Layer number or name ('-1' for all layers)
A single vector map can be connected to multiple database tables. This number determines which table to use. When used with direct OGR access this is the layer name.
Default: -1
type=string [,string,...]
Input feature type
Allowed values: point, line, boundary, centroid, area, face, kernel
Default: point,line,area,face
coordinates=east,north [required]
Coordinates for query
'-' for standard input
distance=float
Query threshold distance
Default: 0
columns=name [,name,...]
Name of attribute column(s)
Default: all columns
format=name
Output format
Allowed values: plain, shell, json
plain: Plain text output
shell: shell script style output
json: JSON (JavaScript Object Notation)
-a
Print attribute information
-i
Print attribute database connection information
-d
Print topological information (debugging)
Prints internal information for topology debugging
-g
Print the stats in shell script style [deprecated]
This flag is deprecated and will be removed in a future release. Use format=shell instead.
-j
Print the stats in JSON [deprecated]
This flag is deprecated and will be removed in a future release. Use format=json instead.
-m
Print multiple features for each map if they meet the criteria
For JSON, this places features under a "features" key
--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--qq
Very quiet module output
--ui
Force launching GUI dialog
map : str | list[str], required
Name of vector map(s)
Used as: input, vector, name
layer : str | list[str], optional
Layer number or name ('-1' for all layers)
A single vector map can be connected to multiple database tables. This number determines which table to use. When used with direct OGR access this is the layer name.
Used as: input, layer
Default: -1
type : str | list[str], optional
Input feature type
Allowed values: point, line, boundary, centroid, area, face, kernel
Default: point,line,area,face
coordinates : tuple[float, float] | list[float] | str, required
Coordinates for query
'-' for standard input
Used as: input, coords, east,north
distance : float, optional
Query threshold distance
Default: 0
columns : str | list[str], optional
Name of attribute column(s)
Default: all columns
Used as: input, dbcolumn, name
format : str, optional
Output format
Used as: name
Allowed values: plain, shell, json
plain: Plain text output
shell: shell script style output
json: JSON (JavaScript Object Notation)
flags : str, optional
Allowed values: a, i, d, g, j, m
a
Print attribute information
i
Print attribute database connection information
d
Print topological information (debugging)
Prints internal information for topology debugging
g
Print the stats in shell script style [deprecated]
This flag is deprecated and will be removed in a future release. Use format=shell instead.
j
Print the stats in JSON [deprecated]
This flag is deprecated and will be removed in a future release. Use format=json instead.
m
Print multiple features for each map if they meet the criteria
For JSON, this places features under a "features" key
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
map : str | list[str], required
Name of vector map(s)
Used as: input, vector, name
layer : str | list[str], optional
Layer number or name ('-1' for all layers)
A single vector map can be connected to multiple database tables. This number determines which table to use. When used with direct OGR access this is the layer name.
Used as: input, layer
Default: -1
type : str | list[str], optional
Input feature type
Allowed values: point, line, boundary, centroid, area, face, kernel
Default: point,line,area,face
coordinates : tuple[float, float] | list[float] | str, required
Coordinates for query
'-' for standard input
Used as: input, coords, east,north
distance : float, optional
Query threshold distance
Default: 0
columns : str | list[str], optional
Name of attribute column(s)
Default: all columns
Used as: input, dbcolumn, name
format : str, optional
Output format
Used as: name
Allowed values: plain, shell, json
plain: Plain text output
shell: shell script style output
json: JSON (JavaScript Object Notation)
flags : str, optional
Allowed values: a, i, d, g, j, m
a
Print attribute information
i
Print attribute database connection information
d
Print topological information (debugging)
Prints internal information for topology debugging
g
Print the stats in shell script style [deprecated]
This flag is deprecated and will be removed in a future release. Use format=shell instead.
j
Print the stats in JSON [deprecated]
This flag is deprecated and will be removed in a future release. Use format=json instead.
m
Print multiple features for each map if they meet the criteria
For JSON, this places features under a "features" key
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.
DESCRIPTION
v.what outputs the features associated with
user-specified location(s) in user-specified vector map(s).
The tool operates on features which are vector geometry objects,
such as point or area. The result is a list of these features
along with their associated categories for the layer specified by layer.
If there are no categories for the specified layer, the feature
is not included in the result. With layer=-1
(all layers), all features
are included in the result regardless of their categories.
Output content
By default, the closest feature is returned for each coordinate and each vector map if the feature fulfills the geometry query and layer selection criteria. With the -m flag, all matching features are returned, not just the closest one.
If an attribute database connection is defined for a given layer and the -a flag is specified, attributes from the associated attribute table will be returned for each category associated with the feature.
The tool operates on features defined as vector geometry objects as opposed to features defined by categories. Consequently, the output is organized by geometry IDs, to which possible categories and attributes are attached. If multiple geometries have the same category, the same set of attributes is repeated for each geometry.
The output also includes the coordinates used in the query, the vector map name, and the mapset. For vector lines, the length is returned. The -d flag returns internal topological information.
JSON output
With format="json"
, a list of matching features is returned.
Each feature includes the geometry ID (id
), geometry type (type
),
vector map name (map
and mapset
), and the relevant part of the spatial
query (coordinates
).
If the feature has associated categories for the given layer,
they are included under data
in a list of items with layer
and category
values.
With -a, data
will also include attributes
for each category
.
A feature is not included in the result if there are no categories
for the specified layer. For layer=-1
, all features
are included in the result and each feature's data
will contain all
associated categories in all layers.
With the -m flag, each list item contains coordinates, a vector map name,
and a list of matching features under the features
key.
In other words, rather than being organized by feature, the list now contains
lists of features nested under each combination of coordinate pair and vector map.
NOTES
The -g and -j flags are deprecated and will be removed in a future release.
Please, use format="json"
instead.
The behavior of the -d flag for internal topology information is not guaranteed.
EXAMPLE
North Carolina sample dataset example:
Query polygon at given position:
v.what zipcodes_wake coordinates=637502.25,221744.25
Find closest hospital to given position within given distance (search radius):
v.what hospitals coordinates=542690.4,204802.7 distance=2000000
Extracting categories from JSON output using Python:
import json
import grass.script as gs
result = gs.read_command(
"v.what",
map="hospitals",
coordinates=[542690.4, 204802.7],
distance=2000000,
flags="a",
format="json",
)
data = json.loads(result)
print(data[0]["data"])
Possible output:
[{'layer': 1, 'category': 22, 'attributes': {'cat': 22, 'OBJECTID': 22, 'AREA': 0, 'PERIMETER': 0, 'HLS_': 22, 'HLS_ID': 22, 'NAME': 'Randolph Hospital', 'ADDRESS': '364 White Oak St', 'CITY': 'Asheboro', 'ZIP': '27203', 'COUNTY': 'Randolph', 'PHONE': '(336) 625-5151', 'CANCER': 'yes', 'POLYGONID': 0, 'SCALE': 1, 'ANGLE': 1}}]
The whole JSON may look like this:
[
{
"coordinate": {
"easting": 542690.40000000002,
"northing": 204802.70000000001
},
"map": "hospitals",
"mapset": "PERMANENT",
"id": 22,
"type": "point",
"data": [
{
"layer": 1,
"category": 22,
"attributes": {
"cat": 22,
"OBJECTID": 22,
"AREA": 0,
"PERIMETER": 0,
"HLS_": 22,
"HLS_ID": 22,
"NAME": "Randolph Hospital",
"ADDRESS": "364 White Oak St",
"CITY": "Asheboro",
"ZIP": "27203",
"COUNTY": "Randolph",
"PHONE": "(336) 625-5151",
"CANCER": "yes",
"POLYGONID": 0,
"SCALE": 1,
"ANGLE": 1
}
}
]
}
]
SEE ALSO
d.what.rast, d.what.vect, v.rast.stats, v.vect.stats, v.what.rast, v.what.rast3, v.what.vect, r.what
AUTHOR
Trevor Wiens
Edmonton, Alberta, Canada
SOURCE CODE
Available at: v.what source code
(history)
Latest change: Thursday Sep 04 02:30:01 2025 in commit 33644dd