| title | description |
|---|---|
BC Address Geocoder Developer Guide |
Locate and standardize your addresses with the BC Address Geocoder. |
This guide is aimed at developers and web masters that would like to incorporate the Physical Address Geocoder into their applications and websites.
Introduction
API Changes
Resource Overview
Cross-Origin Resource Sharing
URL encoding
addresses Resource
occupants/addresses Resource
occupants/nearest Resource
Resource Representations
About Query Representation
Site Address Representation
Occupant Address Representation
Intersection Address Representation
About faults
Implementing address autocompletion in your application
API reponse error code
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.
A summary of changes to the BC Address Geocoder can be found on the What's New page for each release.
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/
To acquire an apikey with a rate limit of 1000 requests per minute, visit the API Services Portal. Once an API key has been acquired, you can explore the API using the API console.
CORS is enabled for any domain if you include an apikey with each request.
Geocoder requests should use the ASCII character set. Characters found in an address that are not ASCII should be encoded. For example, a '#' would be encoded as '%23'.
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:
- 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 - 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:
- Geocode 456 Gorge Rd E, Victoria, BC
https://geocoder.api.gov.bc.ca/addresses.xhtml?addressString=456%20Gorge%20Rd%20e%20victoria%20bc - Geocode 7-955 13th Ave, Valemount, BC
https://geocoder.api.gov.bc.ca/addresses.xhtml?addressString=7-955%2013th%20ave,%20Valemount,bc - Geocode the intersection at Johnson and Government
https://geocoder.api.gov.bc.ca/addresses.xhtml?addressString=johnson%20and%20government - 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 - 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 - 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 - 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 - 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 - 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 - 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 - Geocode 13450 104 ave, Surrey, BC
https://geocoder.api.gov.bc.ca/addresses.xhtml?addressString=13450%20104%20ave%20surrey%20bc - Reverse geocode the longitude/latitude location returned by example 11. This should return 13450 104 ave, Surrey, BC. Note that reverse geocoding a point means finding the nearest known address to that point which is why the resource is called sites/nearest.
https://geocoder.api.gov.bc.ca/sites/nearest.xhtml?point=-122.8491387,49.1914645 - 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 - Geocode a Surrey address and limit address search to Surrey
https://geocoder.api.gov.bc.ca/addresses.xhtml?localities=surrey&addressString=13450%20104%20ave%20surrey%20bc - Geocode a Surrey address and limit address search to Richmond. This will return a fullAddress of BC which means no match.
https://geocoder.api.gov.bc.ca/addresses.xhtml?localities=richmond&addressString=13450%20104%20ave%20surrey%20bc - Geocode a Surrey address and limit address search to Surrey and Richmond.
https://geocoder.api.gov.bc.ca/addresses.xhtml?localities=richmond,surrey&addressString=13450%20104%20ave%20surrey%20bc
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.
-
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 -
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
The occupants/nearest resource represents the nearest site to a given point location
- Find the nearest courthouse to a given point
https://geocoder.api.gov.bc.ca/occupants/nearest.geojson?point=-123.7064038,48.8498537&tags=courts
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.
| Attribute Name | Type |
|---|---|
| searchTimestamp | Datetime |
| executionTime | Real |
| version | String |
| minScore | Integer |
| maxResults | Integer |
| echo | Boolean |
| interpolation | String |
| outputSRS | Integer |
| setBack | Real |
| Attribute Name | Type |
|---|---|
| fullAddress | String |
| score | integer |
| matchPrecision | String |
| precisionPoints | integer |
| faults | String |
| siteName | String |
| unitDesignator | String |
| unitNumber | String |
| unitNumberSuffix | String |
| civicNumber | String |
| civicNumberSuffix | String |
| streetName | String |
| streetType | String |
| isStreetTypePrefix | Boolean |
| streetDirection | String |
| isStreetDirectionPrefix | Boolean |
| streetQualifier | String |
| localityName | String |
| localityType | String |
| electoralArea | String |
| provinceCode | String |
| locationPositionalAccuracy | String |
| locationDescriptor | String |
| siteID | string |
| blockID | String |
| fullSiteDescriptor | String |
| accessNotes | String |
| siteStatus | String |
| siteRetireDate | Date |
| changeDate | string |
| isOfficial | string |
| Attribute Name | Type |
|---|---|
| fullAddress | String |
| intersectionName | String |
| localityName | String |
| provinceCode | String |
| score | Integer |
| matchPrecision | String |
| precisionPoints | Integer |
| provinceCode | String |
| matchPrecision | String |
| precisionPoints | Integer |
| faults | String |
| intersectionID | String |
| degree | String |
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.
| Attribute Name | Type |
|---|---|
| occupantName | string |
| occupantID | string |
| occupantAliasAddress | string |
| occupantDescription | string |
| contactEmail | string |
| contactPhone | string |
| contactFax | string |
| websiteUrl | string |
| imageUrl | string |
| keywords | string |
| businessCategoryClass | string |
| businessCategoryDescription | string |
| naicsCode | string |
| dateOccupantUpdated | string |
| dateOccupantAdded | string |
| custodianId | string |
| sourceDataId | string |
The faults property in a resource response is a list of one or more address match faults. Each fault has the following properties:
| Property name | Description | Example |
|---|---|---|
| value | string that caused the fault (new in v4.1) | 7380 |
| element | name of address element at fault | CIVIC_NUMBER |
| fault | fault descriptor | notInAnyBlock |
| penalty | number of points to reduce score by | 1 |
Using the autoComplete boolean request parameter is the key to successful implementation of address autocompletion in your application. Let's assume your application input form has an address text box and a search icon.
A user starts entering the characters of an address. After three or so characters, the application should issue a get request on the addresses resource with autoComplete set to true every time a user enters an additional character. This tells the geocoder that addressString contains a partial address and to find the best N address prefix matches for display in a pick list below the address text box.
If the user clicks on the search icon or presses the Enter key, the application should issue a get request on the addresses resource with autoComplete set to False. This tells the geocoder to use addressString as entered when trying to find the best N matches.
You can also use the autoComplete and exactSpelling parameters in the same request. If exactSpelling is set to true (default is false), autoComplete suggestions will be limited to addresses beginning with the provided partial address.
In addition to exactSpelling, the fuzzyMatch parameter can be included in the same request. If fuzzyMatch is set to true (default is false), autoComplete suggestions will be sorted using a fuzzy match comparison to the addressString.
If you are using jQuery in your javascript app, check out our javascript code for autocompletion here. To see the code in action, visit here
We use Kong API gateway to manage Geocoder API calls. Below is a list of gateway errors. You can skip this section if you installed your own Geocoder.
| Response Code | Error Message | Error Description |
|---|---|---|
| 404 | This page is not found | The path is not defined |
| 401 | No API key found in reques | The API endpoints requires an API key |
| 401 | Invalid authentication credentials | The provided API key is not found |
| 403 | You cannot consume this service | The provided API key is invalid, unapproved or expired. |
| 429 | API rate limit exceeded | Too many requests per minute |
Geocoder can return a number of error response.
| Response Code | Error Message | Error Description |
|---|---|---|
| 400 | Invalid parameter:[details] | The provided parameter is incorrect. Please refer to the details |
| 404 | no Route matched with those values | The path is not found. Please make sure it’s one in document |
| 500 | Anything | This is a general internal error |
In addition to above common error responses there are also a number of errors that can happen occasionally or during the initialization state. These errors usually come with 500s but could also be 400s.
- Invalid or no API key found in request: check for invalid parcel API key.
- Invalid JDBC URL in properties file: database related error.
- No JDBC URL found in properties file: database related error.
- Invalid JDBC URL in properties file: database related error.
- Exception loading database driver: database related error.
- Error connecting to database: database related error.
- Parameter must be in the format: Request format not recognized.
- Unable to parse MatchFault string: unknown internal/data error.
- Unexpected error in coordinate reprojection: unknown data error.
- No value for parameter: unknown internal/data error.
- Parameter must be in UUID format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX: invalid UUID