v.in.gazetteer - GRASS manual

NAME

v.in.gazetteer - Downloads named inhabited places within the current region from OpenStreetMap and classifies them by cartographic symbolism tier.

KEYWORDS

vector, import, gazetteer, OpenStreetMap, places, cartography

SYNOPSIS

v.in.gazetteer

v.in.gazetteer --help

v.in.gazetteer [-l] output=name [place_types=string[,string,...]] [min_population=integer] [language=string] [endpoint=string] [timeout=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-l: List matching places to stdout without creating a vector map
--overwrite: Allow output files to overwrite existing files
--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

output=name [required]: Name for output vector map of classified inhabited places
place_types=string[,string,...]: OSM place=* types to fetch; Options: city, town, village, hamlet, isolated_dwelling, suburb, locality; Default: city,town,village,hamlet,isolated_dwelling
min_population=integer: Minimum population to include (only applied to places carrying a population tag; places without one are always kept)
language=string: Preferred ISO 639-1 language code for place names (uses OSM name:<language> tag when present, falls back to name)
endpoint=string: Overpass API endpoint URL; Default: https://overpass-api.de/api/interpreter
timeout=integer: HTTP request timeout in seconds; Default: 90

DESCRIPTION
NOTES
EXAMPLES
SEE ALSO
REFERENCES
AUTHOR

DESCRIPTION

v.in.gazetteer downloads named inhabited places (cities, towns, villages, hamlets, and isolated dwellings) within the current computational region from OpenStreetMap, via the public Overpass API, and imports them as a point vector map classified by cartographic symbolism tier.

The module reads the current region (g.region), reprojects its extent to WGS84 lon/lat, queries Overpass for place=* nodes within that bounding box, and imports the result with v.import (which reprojects the WGS84 points into the current project's CRS automatically).

Cartographic symbolism

Each place is assigned a rank (1-5) following the French IGN convention (ville / bourg / village / hameau / écart) and the equivalent international topographic-mapping convention (city / town / village / hamlet / isolated dwelling) — both use the same importance ordering, and OSM's place=* tag maps onto it directly:

Rank	OSM place=*	French (IGN)	English	symbol_size	label_size	label_style
1	city	ville	city	10	14	bold_upper
2	town, suburb	bourg	town	7	11	bold
3	village	village	village	5	9	regular
4	hamlet	hameau	hamlet	3	7	italic
5	isolated_dwelling, locality	écart	isolated dwelling	2	6	italic_small

symbol_size, label_size, and label_style are suggested styling values for later display with d.vect or ps.map; this module only classifies and attributes points, it does not render a map itself.

Output attribute columns: name, place (raw OSM tag), population (when available), rank, rank_fr, rank_en, symbol_size, label_size, label_style, source.

Filtering

The place_types option selects which OSM place=* values to fetch (default: city, town, village, hamlet, isolated_dwelling). The min_population option drops places below a population threshold, but only when they carry an OSM population tag — places without one are always kept, since population coverage in OSM is inconsistent for smaller settlements. The language option prefers a name:<language> tag (e.g. language=fr) over the default name tag when present.

Listing without importing

The -l flag prints matching places (rank, English rank label, name, population) to stdout instead of creating a vector map — useful for a quick check before committing to an import.

NOTES

Requires the Python requests package.
Requires network access to the configured Overpass endpoint (default: the public overpass-api.de instance). Point the endpoint option at a mirror (e.g. a Kumi Systems instance) if the default is rate-limited or unreachable.
The region-to-WGS84 reprojection uses all four region corners (not just two opposite corners), which stays correct for skewed or rotated projected regions, but remains an approximation for very large or high-latitude extents under non-conformal projections.
OSM population figures are user-contributed and not authoritative; treat min_population filtering as a coarse cut, not a precise demographic filter.

EXAMPLES

Import all default place types in the current region:

g.region n=47.73 s=47.68 e=-2.85 w=-2.93
v.in.gazetteer output=places_plumergat

Only cities and towns above 10,000 inhabitants, preferring French names:

v.in.gazetteer output=places_major place_types=city,town \
  min_population=10000 language=fr

List matches without importing:

v.in.gazetteer -l output=dummy place_types=village,hamlet

Style output by rank afterward, e.g. with d.vect:

d.vect places_plumergat where="rank=1" icon=basic/circle size=10 color=red
d.vect places_plumergat where="rank=4" icon=basic/circle size=3 color=grey

REFERENCES

AUTHOR

Yann Chemin

SOURCE CODE

Available at: v.in.gazetteer source code (history)

Accessed: Monday Jul 27 12:30:44 2026