Skip to content
Joel Natividad edited this page Nov 15, 2026 · 32 revisions

Geospatial

Tier: Intermediate Commands covered: geocode, geoconvert

Note

Per-command flag reference lives in /docs/help/. This page is the workflow layer — when to reach for each command and how they compose.

Two commands, big footprint. geocode handles forward geocoding, reverse geocoding, city suggestions, IP geolocation, and country info — all against a local Geonames index plus an optional MaxMind GeoLite2 database. No network round-trip per row, 360,000 records / sec with caching and multithreading. It can also geocode online via the OpenCage API (the opencage / opencagenow subcommands) when you need true street-address geocoding that the local city index can't do. For New York City, the geoclient / geoclientnow subcommands use NYC's own Geoclient API, which also returns BBLs, BINs, council districts, census tracts and other NYC attributes. For any US address or coordinate, the census / censusnow subcommands use the free, keyless US Census Geocoder, returning the state, county, tract, block group and block GEOIDs you need to join Census statistics.

geoconvert flips between CSV/SVG and spatial formats (GeoJSON, GeoJSONL, SHP).

Quick decision table

If you want to… Use Notes
Find lat/lon from a city name geocode suggest Jaro-Winkler fuzzy matching
Resolve small-town place names the default index misses geocode index-load 1000 The denser cities1000 prebuilt (details)
Find the nearest city to a lat/lon geocode reverse Local index; no API rate limits
Find country code from an IP geocode iplookup Needs MaxMind GeoLite2-City.mmdb
Enrich with US state/county FIPS codes geocode suggest / reverse with FIPS dyncols Census data prep
Geocode a full street address (online) geocode opencage OpenCage API; needs an API key
Reverse-geocode a coordinate to a full address (online) geocode opencage Same subcommand; mode auto-detected
Geocode a New York City address, BBL or BIN (online) geocode geoclient NYC Geoclient API; needs a free NYC API key (details)
Geocode a US address or coordinate to Census tract/block GEOIDs (online) geocode census US Census Geocoder; free, no key; batch for large files (details)
Manage / prune the OpenCage, Geoclient and Census result caches geocode cache-* cache-clear, cache-prune, cache-info
CSV → GeoJSON for QGIS / web maps geoconvert Specify --geometry for WKT or lat/lon
GeoJSON / SHP → CSV geoconvert Drops to a flat tabular form
Plot lat/lon points on an interactive map viz map Tile basemap; point or --density heatmap
Plot lat/lon on an offline projection map viz geo ScatterGeo projection — no tiles or token; --projection

geocode

Twenty-one subcommands; the big four are suggest, suggestnow, reverse, reversenow. Plus iplookup / iplookupnow, countryinfo / countryinfonow, the online opencage / opencagenow, geoclient / geoclientnow and census / censusnow subcommands, the geocode index-* subcommands for managing the local Geonames cities index, and the geocode cache-* subcommands for managing the on-disk OpenCage, Geoclient and Census result caches.

Setting up the index

# Downloads the prebuilt Geonames cities15000 index (~26k cities, pop > 15k)
qsv geocode suggest --help    # first run triggers the download

# Manage the local index
qsv geocode index-check                    # show index metadata; check for updates
qsv geocode index-update                   # rebuild from the latest Geonames data
qsv geocode index-load my_index.rkyv       # load a custom-built .rkyv index file
qsv geocode index-load 1000                # fetch the denser cities1000 prebuilt
qsv geocode index-reset                    # restore the default prebuilt cities15000 index

Old indexes are cleaned up automatically (#4776). The index file is named for the qsv release (qsv-29.0.0-geocode-index.rkyv), so every upgrade downloads a new one. When qsv downloads a new release's index, it keeps the index files of the 5 most recent releases and deletes the rest, printing what it removed. Only files named the way qsv names them are touched. Backups (.bak) and other files stay, and the active index (including one picked with QSV_GEOCODE_INDEX_FILENAME) is always kept. Run qsv geocode index-reset to clean up an existing cache right away.

index-update keeps your index's city set and languages. --cities-url and --languages default to what the current index was built with, so a plain index-update on a cities1000 or multi-language index keeps it that way. Passing a different value forces a rebuild. --languages is case-insensitive and ignores spaces (EN, fr works), and --force can build an index when none exists yet.

Region names fall back like city names. When the index has no translation of a region (admin1), county (admin2) or country name in the requested language, qsv prints the untranslated name, e.g. "Maputo, Maputo City MZ". A -l/--language the index wasn't built with prints a warning that says how to rebuild for it.

Parallel runs on a fresh install are safe. The downloaded index is written to a temporary file beside it and renamed into place in one step, so other geocode runs (a parallel worker, a second terminal) see either no index or a complete one. This also applies to index-load <N>.

For IP-based lookups, manually download GeoLite2-City.mmdb from your MaxMind account (free) and copy it to ~/.qsv-cache/ (or set QSV_GEOIP2_FILENAME).

Choosing a population floor

The default index is cities15000 — every populated place with a population over 15,000. That floor is usually the binding constraint when a place name fails to resolve: the town exists in Geonames, just not in this index.

index-load accepts a published population floor as a shortcut: 15000 and 1000 are published prebuilts, so reaching the denser index is one command instead of a full local rebuild.

Floor Places Prebuilt index Download How to get it
15000 (default) ~26k worldwide 22.6 MiB — ships by default; geocode index-reset restores it
1000 ~140k worldwide 82.7 MiB (32 MiB compressed) one command qsv geocode index-load 1000

index-load <floor> downloads a prebuilt, English-only index built for your qsv version. Contrast with qsv geocode index-update --cities-url 1000, which pulls the ~200 MB Geonames source dump and rebuilds from scratch — still the right call when you need non-English place names (its --languages option), but slow and unnecessary if you only want more coverage in English.

Important

The default stays cities15000 on purpose. index-load swaps the index for every subsequent geocode run, and a denser index costs roughly 4× the index size and gives different suggest results — a small town can now outrank the large city you were matching before. Load 1000 because your data is full of small places, not as a blanket upgrade.

It is also not a fix for cross-country mis-resolution (a US city name matching a same-named place abroad). That is a country-filter problem, not a density problem, and it reproduces identically against a cities1000 index — constrain the lookup with --country instead.

A floor this binary knows about can still be missing from the release it was built from. When that happens the download failure names the release and points at the local-rebuild alternative instead of surfacing a bare 404.

How index-load installs an index

index-load validates the file with the same metadata API that index-check uses, prints Found index file:, and reports validity only once the index has loaded. It then copies the file into place; a failed copy is an error. qsv geocode index-load 1000 stages its download in the geocode cache dir as cities1000.rkyv.sz, which doubles as a warm copy for a later re-install.

Note

Downloads fail on any non-2xx HTTP response and name the status — for geocode index fetches, validate's remote JSON Schema, and sample / snappy remote inputs. An error page is never saved as the file.

Forward geocoding (suggest)

Example: enrich a list of city names with coordinates

# input has a "city" column with values like "Brooklyn", "san jose", "PARIS"
qsv geocode suggest city \
  --new-column 'lat,lon' \
  --formatstr "%latitude,%longitude" \
  cities.csv > cities_with_coords.csv

Example: US-only suggestion that also pulls FIPS codes (for Census joins)

qsv geocode suggest city_col --country US -f \
  "%dyncols: {geocoded_city:name},{state:admin1},{county:admin2},\
{state_fips:us_state_fips_code},{county_fips:us_county_fips_code}" \
  voters.csv -o voters_with_fips.csv

The %dyncols: directive expands to multiple new columns named on the left of each : pair.

Restricting to a state or province (--admin1)

# a column of Florida city names
qsv geocode suggest city --admin1 US.FL -f "{name}, {admin1}" fl_cities.csv

How --admin1 filters:

  • --admin1 is a strict filter. Only a place inside the listed admin1s is returned. A value with no match there is left unchanged (or set to --invalid-result), and stderr reports how many. Small towns missing from the default index are the usual cause of a miss, and index-load 1000 finds more of them (choosing a population floor).
  • US territories work: US.PR, US.VI, US.GU, US.AS and US.MP. Geonames files them as countries of their own; qsv maps them. An explicit --country US admits them too.
  • Mixed code lists infer every country, so --admin1 US.NY,US.PR needs no --country. Admin1 names still need --country.
  • Admin1 codes are case-insensitive: --admin1 us.ca works like US.CA. Matching is by prefix, and a few full Geonames codes are prefixes of others: KZ.12 also matches KZ.12510143.
  • Exact names win. The fuzzy search treats any name that merely starts with the value as a perfect match and breaks ties by population, but a place whose own name is the value wins (so "Davis" returns Davis, not San Diego), with or without --admin1.

Reverse geocoding (reverse)

Example: reverse-geocode NYC 311 lat/lon to Borough / NTA

qsv geocode reverse 'Location' \
  --new-column 'nearest_city,admin1,admin2' \
  --formatstr "%name,%admin1,%admin2" \
  --country US \
  NYC_311_SR_2010-2020-sample-1M.csv > nyc311_reversed.csv

Location is the source column in "lat, lon" or "(lat, lon)" format.

Example: reverse-geocode FIPS codes for downstream Census tract joins

qsv geocode reverse coordinate_col --country US -f \
  "%dyncols: {city:name},{state:admin1},{county:admin2},\
{state_fips:us_state_fips_code},{county_fips:us_county_fips_code}" \
  events.csv -o events_with_fips.csv

Census joins need the 5-digit county GEOID. us_county_fips_code is the 3-digit county part (003), unique only within a state — prefix it with us_state_fips_code (e.g. -f '{us_state_fips_code}{us_county_fips_code}' → 42003). Regenerate any file enriched with us_county_fips_code by qsv 24.0.0 or earlier — those builds dropped the first digit of county codes ≥ 100 (#4771). See US Census Integration.

One-shot variants (suggestnow, reversenow, countryinfonow)

For ad-hoc one-off lookups from the command line (not a CSV):

qsv geocode suggestnow "Brooklyn"
qsv geocode reversenow "40.6782, -73.9442"
qsv geocode countryinfonow US

IP lookup (iplookup)

Needs the MaxMind GeoLite2-City.mmdb, which you download yourself (a free MaxMind account is required) and copy to ~/.qsv-cache/, or point to with QSV_GEOIP2_FILENAME.

GeoLite2 finds the IP's city, and qsv then returns that city's record from the local Geonames index. So iplookup takes the same --formatstr formats as suggest/reverse, and its default output is %city-admin1-country (e.g. San Francisco, California US). If the IP can't be located, or its city isn't in your Geonames index (a small town missing from the default cities15000, for example), the IP itself is returned. A URL is resolved to its host's IP first.

qsv geocode iplookup -f %country --new-column country ip_col logs.csv > logs_with_country.csv
qsv geocode iplookupnow 208.67.222.222       # San Francisco, California US: 37.77493, -122.41942

Country info (countryinfo)

qsv geocode countryinfo country_code visitors.csv > with_country_info.csv
# Adds columns: name, capital, area, population, languages, currency, ...

Online geocoding with OpenCage (opencage, opencagenow)

suggest / reverse are city-level and offline — fast, but they can't resolve a full street address. When you need real address geocoding, opencage calls the online OpenCage API. One subcommand does forward (address → coordinates) and reverse (coordinates → address) geocoding — the mode is auto-detected per row (pass --reverse to force reverse).

Compared with more popular commercial geocoders such as Google Maps, OpenCage is built on open data, chiefly OpenStreetMap, so its results come with far fewer strings (details):

  • you may store results as long as you like, even after you stop being a customer, which is what lets qsv keep them in a persistent cache;
  • results can be displayed on any map;
  • results may be used commercially, behind a firewall or publicly;
  • pricing is a flat monthly or annual fee;
  • bad results can be fixed at the source by correcting OpenStreetMap.

Requires an OpenCage API key — set it with --api-key or the QSV_OPENCAGE_API_KEY environment variable. A free trial key (https://opencagedata.com/users/sign_up) allows 2,500 requests/day at 1 request/second, for testing only: OpenCage's FAQ asks that production use go on a paid plan.

# forward-geocode a column of street addresses to coordinates
qsv geocode opencage address --new-column coordinates -f %location addresses.csv

# reverse-geocode "(lat, lon)" coordinates to a full formatted address (the default format)
qsv geocode opencage Location --reverse --new-column address events.csv

# pull individual OpenCage components with dotted dynamic formatting
qsv geocode opencage address -f '{components.city}, {components.country}' addresses.csv

# add multiple columns in one pass with the %dyncols: directive
qsv geocode opencage address \
  -f '%dyncols: {city:components.city}, {postcode:components.postcode}, {tz:annotations.timezone.name}' \
  addresses.csv

# one-off lookups from the shell
qsv geocode opencagenow "1600 Pennsylvania Ave NW, Washington DC"
qsv geocode opencagenow "40.71427, -74.00597"

OpenCage's terms of service permit caching, so results are kept in a persistent on-disk cache (separate from the Geonames index, in {cache-dir}/geocode-opencage_v1) — re-runs and duplicate queries never re-hit the API (--cache-ttl sets the TTL; --no-cache disables it). Rows are processed sequentially behind a rate limiter (--rate-limit, default 1 request/sec — the free-tier limit), so reach for opencage for enrichment quality and for the offline subcommands for raw throughput. Inspect and clean up that cache with the cache-* subcommands.

Key and response safety. OpenCage takes your key as a key= URL parameter; qsv logs it as key=REDACTED. Earlier releases logged the key in full, so if you ran geocode opencage with logging on, check old qsv log files for your key. OpenCage responses over 4 MiB are refused rather than read into memory, and the row counts as a failed lookup.

OpenCage --formatstr options: %formatted (default — the full formatted address), %lat-long, %location, %city, %state, %county, %country, %country_name, %postcode, %confidence, %json, %pretty-json; plus dotted dynamic keys {components.<name>} and {annotations.<dotted.path>}. The %dyncols: directive works here too — %dyncols: {city:components.city}, {tz:annotations.timezone.name} adds several columns to the output CSV in one pass (it cannot be combined with --new-column).

NYC geocoding with Geoclient (geoclient, geoclientnow)

For New York City data, geoclient geocodes through the city's own Geoclient v2 API, a REST wrapper around the Department of City Planning's Geosupport. Beyond coordinates it returns the NYC identifiers and districts that general geocoders don't have: BBL, BIN, community district, city council district, census tracts (2010 and 2020), NTA, ZIP code, and many more fields. It only geocodes locations in the five boroughs.

The public API needs a free subscription key: sign up at https://api-portal.nyc.gov and subscribe to the "Geoclient V2 User" product. Pass it with --api-key or the QSV_GEOCLIENT_API_KEY environment variable. qsv sends the key as a request header, so it never appears in a URL or a log. To use a self-hosted Geoclient instead, set QSV_GEOCLIENT_API_URL to its base URL (e.g. http://localhost:8080/geoclient/v2). A self-hosted instance needs no key and has no quota.

--endpoint picks the kind of lookup:

Endpoint Input
search (default) A free-form location in the column: 314 W 100 St Manhattan, a landmark, an intersection, a BBL or a BIN
bin A Building Identification Number
bbl A Borough-Block-Lot: 1000670001, 1-67-1, 1/00067/0001, or a spreadsheet float such as 1000670001.0
address, addresspoint, intersection, place, blockface Several columns, mapped with --params
# free-form NYC addresses -> "lat, lon" (the default format)
qsv geocode geoclient address --api-key YOURKEY nyc_311.csv

# BBLs (e.g. from PLUTO) -> separate latitude/longitude columns
qsv geocode geoclient bbl --endpoint bbl -f '%dyncols: {lat:latitude}, {lng:longitude}' pluto.csv

# structured address columns -> BBL and council district in new columns
qsv geocode geoclient Street --endpoint address \
  --params "houseNumber={HouseNo},street={Street},borough={Borough}" \
  -f '%dyncols: {bbl:bbl}, {council:cityCouncilDistrict}, {tract:censusTract2020}' \
  permits.csv

# one-off lookups
qsv geocode geoclientnow "350 5th Ave Manhattan"
qsv geocode geoclientnow --endpoint bbl -f '%pretty-json' 1008350041

--params maps Geoclient parameter names to input columns (name={Column}) or to fixed values (name=value). Parameter names are case-sensitive, and are checked before any request is sent:

  • address, addresspoint: houseNumber, street, and borough or zip
  • intersection: crossStreetOne, crossStreetTwo, borough, plus optional boroughCrossStreetTwo and compassDirection
  • place: name, and borough or zip
  • blockface: onStreet, crossStreetOne, crossStreetTwo, borough, plus optional boroughCrossStreetOne, boroughCrossStreetTwo and compassDirection

A borough can be a name, an abbreviation (MN, BX, BK, QN, SI) or a number from 1 to 5. With a structured endpoint, the <column> argument is not sent to the API. It only names the column that is replaced with the result, or that --rename applies to. Use -c to add the result as a new column instead. For search, --params can set fixed search options such as exactMatchMaxLevel=5.

Formats: %+ / %lat-long (default), %location, %bbl, %bin, %json, %pretty-json, {field} templates with any result field (e.g. "{bbl} - CD {communityDistrict}"), and %dyncols:. Geosupport pads some fields with spaces, such as censusTract2020; qsv trims them. A field missing from a result renders empty. bbl and bin lookups return no street-front coordinate, so for those latitude/longitude are the building's internal label point.

Throughput and quotas: there is no batch endpoint, so every distinct location is one request. The public API allows 100 requests/second per IP, 2,500/minute and 500,000/day. qsv sends --jobs requests at a time behind a rate limiter. The limiter defaults to 40 requests/second, just under the per-minute cap; set it with --rate-limit. Repeated locations within a batch are looked up once, results are cached on disk, and a location Geoclient can't geocode is left unchanged or set to --invalid-result. Rate-limited and server-error responses are retried up to 3 times. If 10 requests in a row still fail, the run stops with a message about the quota rather than grinding through the rest of the file. A bad key stops it at the first request, and the error includes the gateway's own reason (e.g. "invalid subscription key", or "missing subscription key"), which tells you which to fix.

Ambiguous searches and reject reasons: a free-form search without a borough is tried in all five boroughs, and a common address can match in several. For example, 100 Broadway exists in Manhattan, Brooklyn, Queens and Staten Island. qsv treats such a row as not geocoded, rather than silently picking one. Add the borough or ZIP code to the input. If exactly one of the matches is an exact match, it is used. A warning at the end reports how many rows were ambiguous. To see why a row didn't geocode, add a %dyncols column whose key starts with _reject.. These keys are filled only on rows that failed. _reject.message gives Geosupport's own reason (e.g. ADDRESS NUMBER OUT OF RANGE), or the boroughs an ambiguous search matched, with [street only] marking a borough where only the street's address range matched, not a property. Other keys include _reject.reasonCode, _reject.message2 and _reject._resultCount. Successful results also carry _resultCount and, for search, _level. (25.0.0.)

qsv geocode geoclient Address addresses.csv \
  -f '%dyncols: {lat:latitude}, {lng:longitude}, {why:_reject.message}'

Ready-made output formats: -f %nyc-districts adds 11 columns: borough, community_district, council_district, assembly_district, state_senate_district, congressional_district, police_precinct, school_district, nta2020, census_tract2020 and zip_code. They are filled for address, intersection, place and search results; BBL, BIN and address-point lookups return only the borough. -f %normalized-address prints a single-spaced line such as 314 WEST 100 STREET, NEW YORK, NY 10025, for results with a house number. (25.0.0, #4798.)

qsv geocode geoclient Address complaints.csv -f %nyc-districts

Standardizing street names: --endpoint normalize returns a street name in <column> in Geosupport's normalized form (w 100 st → WEST 100 STREET, bway → BROADWAY). It only reformats and doesn't check that the street exists. --endpoint streetcode turns a 6-, 8- or 11-digit Geosupport street code (e.g. 11361001) into the street's name. An unknown code's reason is available as _reject.message. Both output the name by default and work with geoclientnow. --params "format=C" drops the sort padding (WEST 1 STREET instead of WEST 1 STREET), and length=10 abbreviates names to fit (W 100 ST). (25.0.0, #4797.)

qsv geocode geoclient Street --endpoint normalize --params format=C streets.csv
qsv geocode geoclientnow --endpoint streetcode 11361001

US Census geocoding (census, censusnow)

census geocodes US addresses and coordinates through the US Census Geocoder. It is free and needs no API key. Besides the coordinates and the matched address, it returns the Census geographies a location falls in, with their GEOIDs: state, county, tract, block group and block, plus places, county subdivisions, congressional and state legislative districts, urban areas, ZCTAs and more. Those GEOIDs are the keys for joining Census statistics to your data.

There are three kinds of input:

  • a one-line address in <column> (the default), e.g. 4600 Silver Hill Rd, Washington, DC 20233;
  • an address in several columns, mapped with --params to the parts street, city, state and zip (name={Column} or a fixed name=value). Census needs a street plus a ZIP code, or a street plus city and state. A row without them is not sent and is left unchanged (or set to --invalid-result);
  • a coordinate (lat, long) with --reverse, which returns the geographies at that point.
# one-line addresses -> the five Census GEOIDs, in five new columns
qsv geocode census Address -f %census-geoids addresses.csv

# address columns -> "lat, lon" in a new column
qsv geocode census Address \
  --params "street={Street},city={City},state={State},zip={Zip}" -c latlong file.csv

# coordinates -> census tract and congressional district
qsv geocode census LatLong --reverse \
  -f '%dyncols: {tract:flat.Census Tracts.GEOID}, {cd:flat.120th Congressional Districts.GEOID}' points.csv

# one-off lookups
qsv geocode censusnow -f %pretty-json "4600 Silver Hill Rd, Washington, DC 20233"
qsv geocode censusnow --reverse -f %census-geoids "38.84601, -76.92744"

Output formats: %lat-long (the default), %location, %matched-address, %census-geoids (columns census_state, census_county, census_tract, census_blockgroup and census_block, e.g. 24, 24033, 24033802405, 240338024052, 240338024052004), and %json / %pretty-json. Every result has the same fields: matchedAddress, coordinates.x (longitude) and coordinates.y (latitude), tigerLine.*, addressComponents.*, Census's own geographies verbatim, and flat.<Layer>.<attribute>, the first feature of each layer, e.g. flat.Census Tracts.GEOID. qsv adds _resultCount (how many addresses matched; the first is used), _matchType (Exact or Non_Exact, batch lookups only) and _source (single or batch). Layer names contain spaces, so flat.* fields work in %dyncols: but not in {field} templates. Layer names also vary by vintage: run censusnow -f %pretty-json to see them.

Single and batch lookups: Census has a single-record endpoint (everything, one request per location, 5 per second by default) and a batch endpoint (up to 10,000 rows per upload, much faster). Batch results carry only the matched address, coordinates, TIGER line and match type, and the state, county, tract, block group and block. With --census-mode auto (the default), qsv batches a read chunk when your --formatstr only needs those fields and at least 50 of its locations aren't cached yet. It uploads 2,000 rows at a time, one upload at a time. --census-mode batch always batches (and refuses an output it can't produce, such as %json), and single never does. Output is the same either way: qsv builds the batch result in the same shape as the single one. Batch lookups are only used with Current_* vintages. An address the batch endpoint matches to several addresses (a Tie) is left ungeocoded and counted in a warning. Connecticut batch matches are looked up again one by one: in Current vintages, Connecticut's counties are its 2022 planning regions (e.g. 09110), but a batch result only carries the 2020 county (09003). Coordinates from the two endpoints can differ in their last digit (about 1e-12 degrees), because Census rounds them differently. Batch matching also varies with the load on the Census servers, so batch no-matches and ties are not cached, and a rerun tries them again.

Benchmark and vintage: --benchmark (default Public_AR_Current) picks the address ranges and --vintage (default Current_Current) the geographies, e.g. --vintage Census2020_Current for 2020 Census geographies or ACS2026_Current for the ones the ACS uses (ACS vintages have no blocks). See the vintages list.

Errors, retries and caching work like geoclient: retries with backoff for rate limits and server errors, an abort after 10 failures in a row, and a persistent result cache (--cache-ttl, --no-cache). An HTTP 400 from Census, such as a bad --vintage, stops the run. To use a caching proxy that speaks the same API, such as ucgeocoder, set QSV_CENSUS_GEOCODER_URL to its base URL (e.g. http://localhost:8080/geocoder) and pass --no-cache. The output is the same as against census.gov.

Managing the online result caches (cache-*)

The opencage, geoclient and census subcommands keep their results in persistent on-disk caches: {cache-dir}/geocode-opencage_v3.redb, {cache-dir}/geocode-geoclient_v3.redb and {cache-dir}/geocode-censusgeocoder_v3.redb (the default cache dir is ~/.qsv-cache/). Only those subcommands populate them; the Geonames cities index is managed separately with index-*. Three subcommands manage the caches, and each one applies to all of them. cache-info prints one JSON line per cache, with a provider field.

# wipe the entire OpenCage, Geoclient and Census caches
qsv geocode cache-clear

# delete entries older than a relative age (s/m/h/d/w suffix) or an absolute date
qsv geocode cache-prune --older-than 30d
qsv geocode cache-prune --older-than 2025-01-01

# report the cache dir, entry count, on-disk size and oldest/newest timestamps (JSON)
qsv geocode cache-info

cache-prune is the tool for honoring data-retention policies without discarding the whole cache; cache-info emits a JSON summary you can pipe into other commands: each cache's real entry_count, its oldest_entry/newest_entry timestamps, and any undecodable_entries (which cache-prune removes) (#4966, #4983; details in Stats Cache & Caching).

See also: /docs/help/geocode.md, Geonames, MaxMind GeoLite2, OpenCage API, NYC Geoclient, US Census Geocoder, Recipe: Geographic Enrichment, Lookup Tables — for fallback when geocode misses.

geoconvert

Convert between CSV/SVG and spatial formats. Input formats: geojson, shp (Shapefile), csv. Output formats: csv, svg, geojson, geojsonl — the exact set depends on the input format (see qsv geoconvert --help).

Example: GeoJSON → CSV (for SQL analysis)

qsv geoconvert nta_boundaries.geojson geojson csv > nta.csv
qsv sqlp nta.csv "SELECT borough, COUNT(*) FROM nta GROUP BY borough"

Example: CSV with WKT geometry → GeoJSON for a web map

qsv geoconvert parcels.csv csv geojson --geometry geometry > parcels.geojson

Example: CSV with latitude/longitude columns → GeoJSON, or → a WKT column

qsv geoconvert stations.csv csv geojson --latitude lat --longitude lon > stations.geojson
qsv geoconvert stations.tsv csv csv --latitude lat --longitude lon > stations_wkt.csv   # TSV in, WKT column out

CSV input skips rows it can't place. A row with an empty, unparseable or out-of-range latitude/longitude (beyond ±90/±180), or empty or invalid WKT, is left out. One stderr warning gives the counts and the line of the first one, e.g. Skipped 4 of 6 rows with unusable geometry (1 empty, 2 invalid coordinates, 1 out of range; first at line 2). If every row is skipped, geoconvert fails instead: the columns then likely hold projected coordinates such as State Plane feet, or are swapped. Swapped columns are only caught when the swapped values fall out of range (e.g. US West Coast longitudes near −122); where both are within ±90, as in New York (40.7, −74), they are not detected. CSV input is streamed (a 500k-row lat/lon file needs ~28 MB of memory), reads .tsv/.tab files and takes -d, --delimiter, and a misnamed column is reported before anything is written.

Example: SHP → CSV (drops to tabular form)

qsv geoconvert nyc_boroughs.shp shp csv > nyc_boroughs.csv

A shapefile needs its .shp, .shx and .dbf side by side; a missing one is reported by name. geoconvert does not reproject: if the .prj describes a projected coordinate system (e.g. NY State Plane), it warns, because the coordinates are output unchanged and GeoJSON requires WGS-84 longitude/latitude. Reproject first, e.g. ogr2ogr -t_srs EPSG:4326 out.shp in.shp.

SHP → CSV columns follow the .dbf's field order (a null is an empty cell), and GeoJSON properties get the same stable order. SHP → SVG is supported too.

Example: pick a file via dialog, then convert

qsv prompt -m 'Choose a GeoJSON file' -F geojson \
  | qsv geoconvert - geojson csv > result.csv

Example: combine geocode + geoconvert to enrich and map

# 1. Reverse-geocode NYC 311 to get the borough column
qsv geocode reverse 'Location' --new-column 'borough' \
  --formatstr "%admin2" --country US nyc311.csv > step1.csv

# 2. Convert the lat/lon pairs straight to GeoJSON (rows without coordinates are skipped)
qsv geoconvert step1.csv csv geojson --latitude Latitude --longitude Longitude > nyc311.geojson

See also: /docs/help/geoconvert.md, geocode, Conversion & I/O.

See also

Home · Why qsv? · Tier legend

Quick links

Get Started

Command Reference

Cookbook

Tuning & Internals

Ecosystem

Reference

Legacy

Clone this wiki locally