Skip to content

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