Skip to content

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