A binding to the Ministère des Ressources naturelles et des Forêts' [address geocoder](https://www.donneesquebec.ca/recherche/dataset/adresses-quebec), the Esri `GeocodeServer` published as a CC-BY resource of `Adresses Québec`. It covers Quebec only, and complements the NAR pathway the way [bc_geocode()] does for British Columbia: as a fallback for Quebec addresses [geocode()] cannot place, and as a second positional source to check NAR against – see [qc_validate()].
Usage
qc_geocode(
x,
known = NULL,
min_score = 0,
batch_size = 1000,
rate = 5,
geometry = FALSE,
crs = 4326,
con = NULL
)Arguments
- x
A character vector of address strings, or a data frame of parsed components as [normalize_address()] returns. Components are needed either way, since the floor compares the answer against them; passing a parsed frame just avoids parsing twice.
- known
Components the caller already has, passed to [normalize_address()] when `x` is a character vector. See [nar_known()].
- min_score
Minimum `qc_score`, 0–100, for a result to count. Default `0`, which is off, and **it should usually stay off**: the score does not rank positional quality, and street centroids outscore civic matches – see [nar_qc_precision()] for the measurement. It is here to reproduce a published threshold, not because one is recommended.
- batch_size
Addresses per request, at most 1000, which is the service's own `MaxBatchSize`.
- rate
Requests per second. Default 5.
- geometry
Whether to return an `sf` object. Default `FALSE`.
- crs
CRS for the returned coordinates, default EPSG:4326.
- con
An open NAR connection, optional. It is used only to give the parse of the *caller's* input a gazetteer; the service itself needs nothing local, and the parse of the service's own answer never gets one.
Value
A data frame with one row per input: `input`, `match_method` (`"qc_address"` or `"none"`), `uncertainty_m`, `qc_locator`, `qc_score`, `qc_status`, `qc_address`, `qc_postal`, `qc_reject`, and either `lon`/`lat` or an `sf` geometry column.
What a response means
**unlike the other two online services, this one refuses.** Asked for `Montreal` alone, or for a street that does not exist, it answers `Status = "U"` with no point instead of degrading to a locality centroid. So a response here is already evidence. What it still does is answer about a *street* when it cannot resolve the civic number, and `Loc_name` is the field that separates the two: `qc_address` resolved the address, `qc_street` found only the street. `qc_reject` says which floor a row failed.
**Do not rank by `qc_score`.** The score measures the returned string against the string that was sent, not how much of the address was resolved, and the correct civic point routinely scores *below* a street centroid for the same query – 84.9 against 98.5 for `1 Rue Notre-Dame Ouest, Montreal`. `min_score` is offered because a genuinely poor match does score poorly, but it defaults to `0` and the locator plus the agreement floor are what decide.
It also **normalizes**: given unaccented, loosely typed input it returns the canonical accented form with the street type and cardinal point in Quebec's own vocabulary, plus the postal code. That is what makes [qc_validate()] a check on the address and not only on the coordinate.
Network use and courtesy
**This service batches**, up to 1000 addresses per request, which is why it is the only online binding here that does not cost one request per address – 5,000 addresses is 5 requests, not 5,000. Requests are throttled to `rate` per second. `httr2` and `jsonlite` are required and live in `Suggests`, so the package never contacts the network unless this function is called.
The batch endpoint is used even for a single address, because it is the only one that populates `Loc_name`: `findAddressCandidates` returns the field empty, which would leave a civic match and a street centroid indistinguishable.
Results are subject to the Government of Quebec's terms and the Creative Commons Attribution 4.0 licence.
See also
[geocode()], which can run this as a tier; [qc_reverse_geocode()]; [bc_geocode()] for the BC-only service.
Examples
if (FALSE) { # \dontrun{
qc_geocode("1 Rue Notre-Dame Ouest, Montreal, QC")
# The canonical form the service answers with, from loose input.
qc_geocode("1000 rue de la gauchetiere ouest, montreal")$qc_address
# What was rejected, and why.
qc_geocode("330 rue Saint-Jean, Quebec")$qc_reject
} # }