v.what
Queries a vector map at given locations.
v.what [-daigjm] 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)
-d
Print topological information (debugging)
-a
Print attribute information
-i
Print attribute database connection information
-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
This flag is deprecated and will be removed in a future release. Use format=json instead.
-m
Print multiple features if overlapping features are found
--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: d, a, i, g, j, m
d
Print topological information (debugging)
a
Print attribute information
i
Print attribute database connection information
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
This flag is deprecated and will be removed in a future release. Use format=json instead.
m
Print multiple features if overlapping features are found
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: d, a, i, g, j, m
d
Print topological information (debugging)
a
Print attribute information
i
Print attribute database connection information
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
This flag is deprecated and will be removed in a future release. Use format=json instead.
m
Print multiple features if overlapping features are found
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.what outputs the category number value(s) associated with user-specified location(s) in user-specified vector map layer(s). This module was derived from the d.what.vect module by removing all interactive code and modification of the output for easy parsing. Using the -g flag generates script-style output which is easily parsable.
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
AUTHOR
Trevor Wiens
Edmonton, Alberta, Canada
SOURCE CODE
Available at: v.what source code
(history)
Latest change: Tuesday Sep 02 22:55:54 2025 in commit 3d5f1c0