Government of British ColumbiaGovernment of British Columbia

DevHub

beta
Resource Information

BC Address Geocoder

Developer Guide

This guide is aimed at developers and web masters that would like to incorporate the Physical Address Geocoder into their applications and websites.

Introduction

The BC Physical Address Online Geocoder REST API lets you integrate real-time standardization, validation, and geocoding of physical addresses into your own applications. This document defines aspects of the REST API that are not covered in the OpenAPI definition.

API Changes in v3.4.1

There are two breaking API changes but they only affect the occupants/addresses resource.

  1. In occupants/addresses, if no occupant separator ("**") is found in addressString, addressString is assumed to be an occupant name, not a civic address. In previous versions, if no frontGate ("--") was found, addressString was assumed to be a civic address.
  2. In occupants/addresses, fullAddress now includes an occupant separator "**" as in "Sir Jame Douglas Elementary ** 401 Moss St, Victoria, BC"

API Changes in v3.3.1

There is one breaking API change:
The following anonymous online geocoder URLs are deprecated as of Geocoder v3.3.1 (released Mar 13, 2018) and will be turned off Sep 1, 2018:

https://apps.gov.bc.ca/pub/geocoder

http://apps.gov.bc.ca/pub/geocoder

Resource Overview

The Online Geocoder offers resources for validating and geocoding an address (including public and related business occupants); finding a given site, intersection, and occupant; and finding sites, intersections, and occupants near a point or within an area. The current baseUrl for the online geocoder is:

https://geocoder.api.gov.bc.ca/

This URL allows both public and gated access. Gated access requires an apikey. To get a sandbox apikey with a maximum rate of 1000 requests per minute, visit the geocoder api console. You can get an unrestricted apikey for use in government applications by contacting the DataBC Help Desk

Cross-Origin Resource Sharing (CORS)

CORS is enabled for any domain if you include an apikey with each request.

Addresses Resource

The addresses resource represents all addresses in the geocoder. A request on this resource to find a query address will return one or more matching addresses that are standardized and geocoded (i.e., given a point location on the earth).

A query address can be specified in two different ways:

  1. A single address string containing all elements of an address as in:
    https://geocoder.api.gov.bc.ca/addresses.geojson?addressString=525%20superior%20st,%20victoria,%20bc

  2. Individual address elements as in:
    https://geocoder.api.gov.bc.ca/addresses.geojson?civicNumber=525&streetName=superior&streetType=st&localityName=victoria&provinceCode=BC

Here are some more example geocoder requests:

  1. Geocode 456 Gorge Rd E, Victoria, BC
    https://geocoder.api.gov.bc.ca/addresses.xhtml?addressString=456%20Gorge%20Rd%20e%20victoria%20bc

  2. Geocode 7-955 13th Ave, Valemount, BC
    https://geocoder.api.gov.bc.ca/addresses.xhtml?addressString=7-955%2013th%20ave,%20Valemount,bc

  3. Geocode the intersection at Johnson and Government
    https://geocoder.api.gov.bc.ca/addresses.xhtml?addressString=johnson%20and%20government

  4. Geocode 5671 Malibu Terrace, Nanaimo, BC and return results in GEOJSON and BC Albers projection
    https://geocoder.api.gov.bc.ca/addresses.geojson?outputSRS=3005&addressString=5671%20malibu%20terrace%20nanaimo%20bc

  5. Geocode 5670 Malibu Terrace, Nanaimo and return the location along the road centreline for using in routing
    https://geocoder.api.gov.bc.ca/addresses.kml?locationDescriptor=routingPoint&addressString=5670%20malibu%20terrace%20nanaimo%20bc

  6. Geocode 5670 Malibu Terrace, Nanaimo and return accessPoint set back four metres from the curb towards the inside of the property. Note that only accessPoints can be set back
    https://geocoder.api.gov.bc.ca/addresses.kml?locationDescriptor=accessPoint&setBack=4&addressString=5670%20malibu%20terrace%20nanaimo%20bc

  7. Geocode 5671 Malibu Terrace, Nanaimo, BC without interpolation. In other words, if the geocoder doesn’t have a site with a civic number of 5671, it will fail instead of looking for an address range that contains 5671
    https://geocoder.api.gov.bc.ca/addresses.xhtml?interpolation=none&addressString=5671%20malibu%20terrace%20nanaimo%20bc

  8. Geocode 200 Gorge Rd W, Saanich, BC and limit results to Victoria. It will return 200 Gorge Rd E, Victoria, BC since Gorge Rd E is in Victoria
    https://geocoder.api.gov.bc.ca/addresses.xhtml?localities=victoria&addressString=200%20gorge%20rd%20w%20saanich%20bc

  9. Geocode 1434 Graham St, Kelowna, BC and limit results to ten matches within the greater Kelowna area
    https://geocoder.api.gov.bc.ca/addresses.xhtml?&bbox=-119.8965522070019%2C49.70546831817266%2C-119.2157397287486%2C50.06954472056336&addressString=1434%20Graham%20St%2C%20Kelowna%2C%20BC&maxResults=10

  10. Geocode 1434 Graham St, Kelowna, BC and limit results to ten street-level matches
    https://geocoder.api.gov.bc.ca/addresses.xhtml?&addressString=1434%20Graham%20St%2C%20Kelowna%2C%20BC%20&matchPrecision=street&maxResults=10

  11. Extrapolate the known location of 12 Bushby St from a parcelPoint to get an accessPoint
    https://geocoder.api.gov.bc.ca/addresses.xhtml?setBack=0&minScore=1&maxResults=1&maxDistance=0&interpolation=adaptive&echo=true&outputSRS=4326&addressString=12%20bushby%20st%20victoria%20bc&locationDescriptor=any&extrapolate=true&parcelPoint=-123.349174,2048.407134

occupants/addresses resource

The occupants/addresses resource represents all occupant addresses in the geocoder. A request on this resource to find a query address will return one or more matching occupants and their addresses.

  1. Find up to 10 schools named Sir James Douglas Elementary
    https://geocoder.api.gov.bc.ca/occupants/addresses.json?addressString=Sir%20James%20Douglas%20Elementary&maxResults=10
  2. Find a school named Sir James Douglas Elementary in Victoria
    https://geocoder.api.gov.bc.ca/occupants/addresses.json?addressString=Sir%20James%20Douglas%20Elementary%20%2A%2A%20Victoria

occupants/nearest resource

The occupants/nearest resource represents the nearest site to a given point location

  1. Find the nearest courthouse to a given point
    https://geocoder.api.gov.bc.ca/occupants/nearest.geojson?point=-123.7064038,48.8498537&tags=courts


Resource representations in HTTP Responses

The addresses resource will return a document in the requested format and spatial reference system. Documents in formats that support a header record (e.g., XHTML, KML, GEOJSON, GEOJSONP, GML) will contain a single About Query representation describing the query and its execution, and one or more site address or intersection address representations. Documents in formats that don’t support a header record (e.g., CSV, SHPZ), will contain one or more site/intersection address representations.

About Query Representation

Attribute NameType
searchTimestampDatetime
executionTimeReal
versionString
minScoreInteger
maxResultsInteger
echoBoolean
interpolationString
outputSRSInteger
setBackReal

Site Address Representation

Attribute NameType
fullAddressString
scoreinteger
matchPrecisionString
precisionPointsinteger
faultsString
siteNameString
unitDesignatorString
unitNumberString
unitNumberSuffixString
civicNumberString
civicNumberSuffixString
streetNameString
streetTypeString
isStreetTypePrefixBoolean
streetDirectionString
isStreetDirectionPrefixBoolean
streetQualifierString
localityNameString
localityTypeString
electoralAreaString
provinceCodeString
locationPositionalAccuracyString
locationDescriptorString
siteIDstring
blockIDString
fullSiteDescriptorString
accessNotesString
siteStatusString
siteRetireDateDate
changeDatestring
isOfficialstring

Intersection Address Representation

Attribute NameType
fullAddressString
intersectionNameString
localityNameString
provinceCodeString
scoreInteger
matchPrecisionString
precisionPointsInteger
provinceCodeString
matchPrecisionString
precisionPointsInteger
faultsString
intersectionIDString
degreeString

Occupant/addresses Resource

The occupants/addresses resource is similar to the addresses resource. Its response will include an About Query representation plus one site representation and occupant representation for each address matched.

Occupant Representation

Attribute NameType
occupantNamestring
occupantIDstring
occupantAliasAddressstring
occupantDescriptionstring
contactEmailstring
contactPhonestring
contactFaxstring
websiteUrlstring
imageUrlstring
keywordsstring
businessCategoryClassstring
businessCategoryDescriptionstring
naicsCodestring
dateOccupantUpdatedstring
dateOccupantAddedstring
custodianIdstring
sourceDataIdstring