National Address Register - User Guide
November 2022
Version 1.5 Produced by: Data Integration Infrastructure Division
Contents
Contents
- Revision history
- Purpose of document
- Summary
- Access and availability
- Technology
- Definitions
- Application Programming Interface methods and examples
- Technical specifications
- Useful links
- Appendix
- Contact information
Revision history
| Date | Version | Revision details |
|---|---|---|
| October 27, 2021 | 1.0 | First release of NAR User Guide |
| November 14, 2022 | 1.5 | Addition of non-civic, additional delivery and building usage information for civic addresses where data is available. |
Purpose of document
The purpose of this document is to provide users with a guide to the National Address Register, which has been made accessible through the Government of Canada API (Application Programming Interface) Store.
Summary
The National Address Register (NAR) sets up a standardized address structure and provides a list of valid georeferenced civic addresses in Canada. The addresses are extracted from Statistics Canada's Building Register and were validated by two independent data sources. The addresses do not disclose the identity of any of the residents or businesses at the address and as such are deemed non-confidential. The corresponding mailing version of the address is added and follows Canada Post's addressing guidelines. Non-civic address, additional delivery, and building usage information will be included for civic addresses that have this data available. This first prototype was developed in the context of the Data Strategy Roadmap for the Federal Public Service and in close collaboration with Employment and Social Development Canada to set up address reference data as a service. It is made available for free under the Statistics Canada Open Licence. It allows a user to search by a unique identifier, by address or by geography.
There are two types of searches in the NAR: basic and advanced. The basic search is available using a basic full-text search feature, and the advanced search is available using a query language that is a series of simple elements strung together to form a more complex query.
Access and availability
Before you can use an Application Programming Interface (API), you must subscribe to an API plan. The plan determines whether approvals are required and the frequency of API calls that your application can make. Once your application is subscribed to a plan, the application is assigned a unique User Key. You must use this User Key when you call an API. This API follows the Terms and Conditions of the Government of Canada API Store.
- Data updates take place on a quarterly basis.
- The request limit is 100 hits per minute per user. The maximum number of records that can be extracted per query is 10,000.
Technology
Hyper Text Transfer Protocol Secure (HTTPS) is a standard way of communicating across the Web and includes methods such as GET and POST used with the web service.
The implementation is a RESTful (built using representational state transfer [REST] architecture) web data service over HTTPS protocol, which will return data in JSON (JavaScript Object Notation) language.
REST is an architectural style that specifies constraints, such as the uniform interface, that if applied to a web service induce desirable properties, such as performance, scalability and modifiability, which enable services to work best on the Web.
Definitions
Census division (CD) is the general term for provincially legislated areas (such as county, municipalité régionale de comté and regional district) or their equivalents. In other provinces and the territories where laws do not provide for such areas, Statistics Canada defines equivalent areas for statistical reporting purposes in cooperation with these provinces and territories. Census divisions are intermediate geographic areas between the province/territory level and the municipality (census subdivision).
Census subdivision (CSD) is the general term for municipalities (as determined by provincial/territorial legislation) or areas treated as municipal equivalents for statistical purposes (e.g., Indian reserves, Indian settlements and unorganized territories). Municipal status is defined by laws in effect in each province and territory in Canada.
Economic region (ER) is a grouping of complete census divisions (CDs) (with one exception in Ontario) created as a standard geographic unit for analysis of regional economic activity.
Federal electoral district (FED) is an area represented by a member of the House of Commons. The federal electoral district boundaries used for the 2021 Census are based on the 2013 Representation Order.
Globally unique identifier (GUID) is a hexadecimal unique ID represented in a string format with a length of 36, including dashes (i.e., 12345678-1234-1234-1234-123456789abc). GUIDs are assigned and used within the NAR to permit the referencing of specific entities such as address or location entities (see the Technical specifications section for more details on address and location definition) and the efficient retrieval of their attributes.
Latitude and longitude are coordinates derived from the blockface centroid (when blockface was available). A blockface represents one side of a street between two consecutive features intersecting that street. The features can be other streets or boundaries of standard geographic areas. Blockfaces are used for generating blockface representative points, which in turn are used for geocoding and census data extraction when the street and address information are available.
The OpenAPI Specification, previously known as the Swagger Specification, is a specification for machine-readable interface files for describing, producing, consuming and visualizing RESTful web services.
Application Programming Interface methods and examples
We list numerous types of methods for the Application Programming Interface (API) here:
*Offset functionality (seekFromId) available
Addresses
- GetAddresses*
- GetAddressesByGUID
- SearchAddresses
Locations
- GetLocations*
- GetLocationsByGUID
Geographies
- GetCensusSubDivisions*
- GetCensusSubDivisionsByCode
- GetEconomicRegions*
- GetEconomicRegionsByCode
- GetFederalElectoralDistricts*
- GetFederalElectoralDistrictsByCode*
Offset:
The offset field (seekFromID) for GetAddresses and GetLocations methods will require a GUID to begin returning the next record (not including the GUID used). The offset field (seekFromID) for GetCensusSubDivisions, GetEconomicRegions, and GetFederalElectoralDistricts methods will require the specific geography code to begin returning the next record (not including the code used).
The NAR Swagger file can be found here: NAR Swagger file.
Addresses
Allows users to query and retrieve addresses.
GetAddresses
Returns addresses applicable to a query
Get URL:
/addresses
Parameters:
- naql: Allows users to do more advanced searches (for more details, please refer to the National Address Query Language section below)
- lang: Allows users to indicate the language that query results are to be returned in (overrides Accept-Language HTTP header)
Request:
streetname eq "Main"
/addresses?naql=streetname%20eq%20%22Main%22
Response:
- The submitted naql request
- 0 or more address and location globally unique identifiers (GUIDs)
- The official version of the civic address
- The postal version of the civic address, if applicable
- Geocoding attributes such as X-Y coordinates, aggregated geo classifications (census subdivision [CSD], economic region [ER], federal electoral district [FED])
- The non-civic address attributes such as QSTRM, GPS coordinates and additional address delivery information (PO Box, Site, RR etc), if applicable
- Building Usage, if available
{
"meta": {
"prepared": "",
"test": false,
"contentLanguage": [
"en"
]
},
"search": {
"searchStyle": "complex",
"criteria": "NAQL: streetname eq Main",
"total": 1
},
"data": [
{
"addressId": "21d954e4-2a60-404d-bc84-0f6cdb068238",
"civicNumber": {
"prefix": null,
"number": "170",
"suffix": {
"code": null
}
},
"streetName": "Main",
"streetType": {
"code": "RUE"
},
"streetDirection": {
"code": null
},
"cityName": {
"en": "Hudson"
},
"province": {
"code": "24"
},
"country": {
"code": "CA",
"name": {
"en": "Canada"
}
},
"mailingAddress": {
"streetName": "MAIN",
"streetType": {
"code": "RUE"
},
"streetDirection": {
"code": null
},
"municipalityName": "HUDSON",
"province": {
"code": "QC"
},
"country": {
"code": "CA",
"name": {
"en": "Canada"
}
},
"postalCode": "J0P1H0"
},
"location": {
"locationID": "2de64244-1d04-4bc6-ab46-7795d4e3eb67",
"geoCoordinates": {
"latitude": 45.444111,
"longitude": -74.105388
},
"geographies": [
{
"codes": {
"code": "24074",
"name": {
"en": "Vaudreuil--Soulanges"
}
},
"source": "FED_2016",
"geographicType": "FED"
},
{
"codes": {
"code": "2435",
"name": {
"en": "Montérégie"
}
},
"source": "ER_2016",
"geographicType": "ER"
},
{
"codes": {
"code": "2471100",
"name": {
"en": "Hudson"
}
},
"source": "CSD_2016",
"geographicType": "CSD"
}
]
}
"building": {
"dominionLandSurvey": {
"quarter": "",
"meridian": "",
"x": 7592568.2062,
"y": 1226439.6579
},
"usage": "1",
"additionalDeliveryInformation": ""
}
}
]
}
GetAddressesByGUID
Returns address information for a specified address GUID.
Get URL:
/addresses/{guid}
Parameters:
- guid: In-path parameter indicating GUID of specific address to retrieve information for
- lang: Allows users to indicate the language that query results are to be returned in (overrides Accept-Language HTTP header)
Request:
21eda105-bb11-4f80-8c5a-fc3523bc9ba0
/addresses/21eda105-bb11-4f80-8c5a-fc3523bc9ba0
Response:
- Address and location GUIDs
- The official version of the civic address
- The postal version of the civic address, if applicable
- Geocoding attributes such as X-Y coordinates, aggregated geo classifications (CSD, ER, FED)
- The non-civic address attributes such as QSTRM, GPS coordinates and additional address delivery information (PO Box, Site, RR etc), if applicable
- Building Usage, if available
{
"meta": {
"prepared": "",
"test": false,
"contentLanguage": [
"en"
]
},
"search": {
"searchStyle": "simple",
"criteria": "",
"total": 1
},
"data": [
{
"addressId": "21eda105-bb11-4f80-8c5a-fc3523bc9ba0",
"civicNumber": {
"prefix": "",
"number": "313",
"suffix": {
"code": ""
}
},
"streetName": "Doncaster",
"streetType": {
"code": "ST"
},
"streetDirection": {
"code": ""
},
"cityName": {
"en": "Winnipeg"
},
"province": {
"code": "46"
},
"country": {
"code": "CA",
"name": {
"en": "Canada"
}
},
"mailingAddress": {
"streetName": "DONCASTER",
"streetType": {
"code": "ST"
},
"streetDirection": {
"code": ""
},
"municipalityName": "WINNIPEG",
"province": {
"code": "MB"
},
"country": {
"code": "CA",
"name": {
"en": "Canada"
}
},
"postalCode": "R3N1W7"
},
"location": {
"locationID": "a3ffb8ed-4040-4b1c-8e26-56e25a88cfd3",
"geoCoordinates": {
"latitude": 49.86496,
"longitude": -97.20929
},
"geographies": [
{
"codes": {
"code": "46014",
"name": {
"en": "Winnipeg South Centre"
}
},
"source": "FED_2016",
"geographicType": "FED"
},
{
"codes": {
"code": "4650",
"name": {
"en": "Winnipeg"
}
},
"source": "ER_2016",
"geographicType": "ER"
},
{
"codes": {
"code": "4611040",
"name": {
"en": "Winnipeg"
}
},
"source": "CSD_2016",
"geographicType": "CSD"
}
]
},
"building": {
"dominionLandSurvey": {
"quarter": "NE",
"section": 26,
"town": 10,
"range": 2,
"meridian": "E1",
"x": 5817587.5372,
"y": 1541098.9267
},
"usage": "1",
"additionalDeliveryInformation": ""
}
}
]
}
SearchAddresses
Returns addresses applicable to request query.
Get URL:
/addresses/search
Parameters:
- qstr: Allows users to do a full-text search query string
- lang: Allows users to indicate the language that query results are to be returned in (overrides Accept-Language HTTP header)
- valueLang: Allows users to indicate the language that the qstr parameter should be interpreted as and how the query should be executed (this does not affect the language of the returned query results); for example, /addresses/search?qstr=Gatineau&lang=en&valueLang=fr would return all the addresses containing "Gatineau" based on the French representation of the addresses in the system, while still returning results in the English representation
Request:
313 DONCASTER ST WINNIPEG MB R3N1W7
/addresses/search?qstr=313%20DONCASTER%20ST%20WINNIPEG%20MB%20R3N1W7
Response:
- The submitted address
- 0 or more address and location GUIDs
- The official version of the civic address
- The postal version of the civic address, if applicable
- Geocoding attributes such as X-Y coordinates, aggregated geo classifications (CSD, ER, FED)
- The non-civic address attributes such as QSTRM, GPS coordinates and additional address delivery information (PO Box, Site, RR etc), if applicable
- Building Usage, if available
{
"meta": {
"prepared": "",
"test": false,
"contentLanguage": [
"en"
]
},
"search": {
"searchStyle": "simple",
"criteria": "",
"total": 1
},
"data": [
{
"addressId": "21eda105-bb11-4f80-8c5a-fc3523bc9ba0",
"civicNumber": {
"prefix": "",
"number": "313",
"suffix": {
"code": ""
}
},
"streetName": "Doncaster",
"streetType": {
"code": "ST"
},
"streetDirection": {
"code": ""
},
"cityName": {
"en": "Winnipeg"
},
"province": {
"code": "46"
},
"country": {
"code": "CA",
"name": {
"en": "Canada"
}
},
"mailingAddress": {
"streetName": "DONCASTER",
"streetType": {
"code": "ST"
},
"streetDirection": {
"code": ""
},
"municipalityName": "WINNIPEG",
"province": {
"code": "MB"
},
"country": {
"code": "CA",
"name": {
"en": "Canada"
}
},
"postalCode": "R3N1W7"
},
"location": {
"locationID": "a3ffb8ed-4040-4b1c-8e26-56e25a88cfd3",
"geoCoordinates": {
"latitude": 49.86496,
"longitude": -97.20929
},
"geographies": [
{
"codes": {
"code": "46014",
"name": {
"en": "Winnipeg South Centre"
}
},
"source": "FED_2016",
"geographicType": "FED"
},
{
"codes": {
"code": "4650",
"name": {
"en": "Winnipeg"
}
},
"source": "ER_2016",
"geographicType": "ER"
},
{
"codes": {
"code": "4611040",
"name": {
"en": "Winnipeg"
}
},
"source": "CSD_2016",
"geographicType": "CSD"
}
]
},
"building": {
"dominionLandSurvey": {
"quarter": "NE",
"section": 26,
"town": 10,
"range": 2,
"meridian": "E1",
"x": 5817587.5372,
"y": 1541098.9267
},
"usage": "1",
"additionalDeliveryInformation": ""
}
}
]
}
Locations
Allows users to retrieve locations.
GetLocations
Returns locations.
Get URL:
/locations
Parameters:
- lang: Allows users to indicate the language that query results are to be returned in (overrides Accept-Language HTTP header)
Request:
Retrieve locations.
/locations
Response:
- Address and location globally unique identifiers (GUIDs)
- Geocoding attributes such as X-Y coordinates, aggregated geo classifications (census subdivision [CSD], economic region [ER], federal electoral district [FED])
{
"meta": {
"prepared": "",
"test": false,
"contentLanguage": [
"en"
]
},
"search": {
"searchStyle": "none",
"criteria": null,
"total":
},
"data": [
{
"locationID": "520b316f-b2ec-41bf-8a64-0000000aa537",
"physicalAddress": [
{
"addressId": "228a72b8-3c1b-4734-b1cd-015490686513"
}
],
"geoCoordinates": {
"latitude": 49.910433,
"longitude": -119.382058
},
"geographies": [
{
"codes": {
"code": "59014",
"name": {
"en": "Kelowna--Lake Country"
}
},
"source": "FED_2016",
"geographicType": "FED"
},
{
"codes": {
"code": "5930",
"name": {
"en": "Thompson--Okanagan"
}
},
"source": "ER_2016",
"geographicType": "ER"
},
{
"codes": {
"code": "5935010"
},
"source": "CSD_2016",
"geographicType": "CSD"
}
]
},
{
"locationID": "856dfe0f-d261-475f-91ab-00000477aeb4",
"physicalAddress": [
{
"addressId": "95c5a05e-8000-4420-b80e-3e54acfc0dcd"
}
],
"geoCoordinates": {
"latitude": 52.023374,
"longitude": -113.964395
},
"geographies": [
{
"codes": {
"code": "48029",
"name": {
"en": "Red Deer--Mountain View"
}
},
"source": "FED_2016",
"geographicType": "FED"
},
{
"codes": {
"code": "4850",
"name": {
"en": "Red Deer"
}
},
"source": "ER_2016",
"geographicType": "ER"
},
{
"codes": {
"code": "4808008"
},
"source": "CSD_2016",
"geographicType": "CSD"
}
]
}
]
}
GetLocationsByGUID
Returns location information for a specified location GUID.
Get URL:
/locations/{guid}
Parameters:
- guid: In-path parameter that allows users to retrieve information for a specific location GUID
- lang: Allows users to indicate the language that query results are to be returned in (overrides Accept-Language HTTP header)
Request:
520b316f-b2ec-41bf-8a64-0000000aa537
/locations/520b316f-b2ec-41bf-8a64-0000000aa537
Response:
- Address and location GUIDs
- Geocoding attributes such as X-Y coordinates, aggregated geo classifications (CSD, ER, FED)
{
"meta": {
"prepared": "",
"test": false,
"contentLanguage": [
"en"
]
},
"search": {
"searchStyle": "simple",
"criteria": "",
"total": 1
},
"data": [
{
"locationID": "520b316f-b2ec-41bf-8a64-0000000aa537",
"physicalAddress": [
{
"addressId": "228a72b8-3c1b-4734-b1cd-015490686513"
}
],
"geoCoordinates": {
"latitude": 49.910433,
"longitude": -119.382058
},
"geographies": [
{
"codes": {
"code": "59014",
"name": {
"en": "Kelowna--Lake Country"
}
},
"source": "FED_2016",
"geographicType": "FED"
},
{
"codes": {
"code": "5930",
"name": {
"en": "Thompson--Okanagan"
}
},
"source": "ER_2016",
"geographicType": "ER"
},
{
"codes": {
"code": "5935010"
},
"source": "CSD_2016",
"geographicType": "CSD"
}
]
}
]
}
Geographies
Users can query and retrieve geography code set information.
GetCensusSubDivisions
Returns census subdivision (CSD) information.
Get URL:
/geographies/censusSubDivisions
Parameters:
- lang: Allows users to indicate the language that query results are to be returned in (overrides Accept-Language HTTP header)
Request:
Retrieve CSDs.
/geographies/CensusSubDivisions
Response:
- CSD codes
- CSD name (English and French)
- CSD type
- Source of CSD
{
"meta": {
"prepared": "",
"test": false,
"contentLanguage": [
"en"
]
},
"search": {
"searchStyle": "none",
"criteria": null,
"total": 3605
},
"data": [
{
"codes": {
"code": "2430025",
"name": {
"en": "Frontenac"
}
},
"csdType": {
"en": "MÉ"
},
"source": "CSD_2016",
"geographicType": "CSD"
},
{
"codes": {
"code": "2430030",
"name": {
"en": "Lac-Mégantic"
}
},
"csdType": {
"en": "V"
},
"source": "CSD_2016",
"geographicType": "CSD"
},
{
"codes": {
"code": "2430035",
"name": {
"en": "Marston"
}
},
"csdType": {
"en": "CT"
},
"source": "CSD_2016",
"geographicType": "CSD"
}
]
}
GetCensusSubDivisionsByCode
Returns CSD information for a specified CSD code.
Get URL:
/geographies/censusSubDivisions/{csdCode}
Parameters:
- csdCode: In-path parameter that allows users to retrieve information for a specific CSD code
- lang: Allows users to indicate the language that query results are to be returned in (overrides Accept-Language HTTP header)
Request:
Submit a CSD code: 5935010.
/geographies/censusSubDivisions/5935010
Response:
- CSD code
- CSD name (English and French)
- CSD type
- Source of CSD
{
"meta": {
"prepared": "",
"test": false,
"contentLanguage": [
"en"
]
},
"search": {
"searchStyle": "simple",
"criteria": "",
"total": 1
},
"data": [
{
"codes": {
"code": "5935010",
"name": {
"en": "Kelowna"
}
},
"csdType": {
"en": "CY"
},
"source": "CSD_2016",
"geographicType": "CSD"
}
]
}
GetEconomicRegions
Returns economic region (ERs) information.
Get URL:
/geographies/economicRegions
Parameters:
- lang: Allows users to indicate the language that query results are to be returned in (overrides Accept-Language HTTP header)
Request:
Retrieve ERs.
/geographies/economicRegions
Response:
- ER codes
- ER name (English and French)
- Source of ER
{
"meta": {
"prepared": "",
"test": false,
"contentLanguage": [
"en"
]
},
"search": {
"searchStyle": "none",
"criteria": null,
"total": 76
},
"data": [
{
"codes": {
"code": "1010",
"name": {
"en": "Avalon Peninsula"
}
},
"source": "ER_2016",
"geographicType": "ER"
},
{
"codes": {
"code": "1020",
"name": {
"en": "South Coast--Burin Peninsula"
}
},
"source": "ER_2016",
"geographicType": "ER"
},
{
"codes": {
"code": "1030",
"name": {
"en": "West Coast--Northern Peninsula--Labrador"
}
},
"source": "ER_2016",
"geographicType": "ER"
}
]
}
GetEconomicRegionsByCode
Returns ER information for a specified ER code.
Get URL:
/geographies/economicRegions/{erCode}
Parameters:
- erCode: In-path parameter that allows users to retrieve information for a specific ER code
- lang: Allows users to indicate the language that query results are to be returned in (overrides Accept-Language HTTP header)
Request:
Submit an ER code: 5930.
/geographies/economicRegions/5930
Response:
- ER code
- ER name (English and French)
- Source of ER
{
"meta": {
"prepared": "",
"test": false,
"contentLanguage": [
"en"
]
},
"search": {
"searchStyle": "simple",
"criteria": "",
"total": 1
},
"data": [
{
"codes": {
"code": "5930",
"name": {
"en": "Thompson--Okanagan"
}
},
"source": "ER_2016",
"geographicType": "ER"
}
]
}
GetFederalElectoralDistricts
Returns federal electoral district (FED) information.
Get URL:
/geographies/federalElectoralDistricts
Parameters:
- lang: Allows users to indicate the language that query results are to be returned in (overrides Accept-Language HTTP header)
Request:
Retrieve FEDs.
/geographies/federalElectoralDistricts
Response:
- FED codes
- FED name (English and French)
- Source of FED
{
"meta": {
"prepared": "",
"test": false,
"contentLanguage": [
"en"
]
},
"search": {
"searchStyle": "none",
"criteria": null,
"total": 338
},
"data": [
{
"codes": {
"code": "10001",
"name": {
"en": "Avalon"
}
},
"source": "FED_2016",
"geographicType": "FED"
},
{
"codes": {
"code": "10002",
"name": {
"en": "Bonavista--Burin--Trinity"
}
},
"source": "FED_2016",
"geographicType": "FED"
}
]
}
GetFederalElectoralDistrictsByCode
Returns FED information for a specified FED code.
Get URL:
/geographies/federalElectoralDistricts{fedCode}
Parameters:
- fedCode: In-path parameter that allows users retrieve information for a specific FED code
- lang: Allows users to indicate the language that query results are to be returned in (overrides Accept-Language HTTP header)
Request:
Submit a FED code: 59014.
/geographies/federalElectoralDistricts/59014
Response:
- FED code
- FED name (English and French)
- Source of FED
{
"meta": {
"prepared": "",
"test": false,
"contentLanguage": [
"en"
]
},
"search": {
"searchStyle": "simple",
"criteria": "",
"total": 1
},
"data": [
{
"codes": {
"code": "59014",
"name": {
"en": "Kelowna--Lake Country"
}
},
"source": "FED_2016",
"geographicType": "FED"
}
]
}
National Address Register National Address Query Language
The National Address Register (NAR) allows users to perform simple searches that leverage full-text search capabilities through the qstr parameter of the /addresses/search API method. However, it also allows for more advanced searches using the features of the National Address Query Language (NAQL) through the naql parameter of the /addresses API method.
This advanced search allows structured queries to be performed that can search across the various elements of the addresses of the NAR. The advanced search is accomplished using the NAQL. A query in NAQL (also known as a clause) consists of a field, followed by an operator, followed by one or more values. For example, the following simple query will find all addresses where the civic number is equal to 1212. It uses the "civic number" field, the EQUALS operator and the value (1212).
Example:
civicNumber eq 1212
How to perform an advanced search
The NAR /addresses API method supports the use of the advanced NAQL queries through the naql parameter to query and return resulting addresses.
/addresses?naql=civicNumber%20eq%201212
To perform an advanced search:
1. Add your query using the fields, operators and field values as the value for the NAQL query parameter.
2. Execute a GET request on the resource. You can apply expansions and pagination as you would normally in the NAR representational state transfer (REST) API.
Performing text searches
The CO (contains) operator can be used on text fields, such as civicNumber.suffix, streetName, and others. CO is specific to text, string or character fields and allows users to perform a match on a substring within the field. Users can still use eq (equals) to do an exact match on an entire field.
Supported properties
| Property | Description | Example |
|---|---|---|
| civicnumber or civicnumber.number | Represents the civic number of the address | ?naql=civicnumber eq 123 or civicnumber.number eq 123 |
| civicnumber.prefix | Represents the apartment number | ?naql=civicnumber.prefix eq 123 |
| civicnumber.suffix | Represents the address number suffix | ?naql=civicnumber.suffix eq"A" |
| streetname | Represents the address's street name | ?naql=streetname eq"Main" |
| streettype or streettype.code | Represents the address's street type | ?naql=streettype eq"ST" |
| streetdirection or streetdirection.code | Represents the address's street direction | ?naql=streetdirection eq"N" |
| cityname, cityname.en or cityname.fr | Represents the address's city name | ?naql=cityname eq"Ottawa" |
| province or province.code | Represents the address's province code | ?naql=province eq 11 |
| mailingaddress.postalcode | Represents the address's mailing address postal code | ?naql=mailingaddress.postalcode eq"A0A 0A0" |
Supported operators
| Operator | Description | Example |
|---|---|---|
| eq | Equals | ?naql=streetname eq"Main" |
| co | Contains | ?naql=streetname co"Ma" |
| and | And | ?naql=streetname eq"Main" and cityname eq"Vancouver" |
| or | Or | ?naql=streetname eq"Main" or streetname eq"Laurier" |
| ( ) | Parentheses | ?naql=(streetname eq"Main" or streetname eq"Laurier") and cityname eq"Ottawa" |
Technical specifications
National Address Register—Data model
Location (locationId) vs. address (addressId)
Location is referencing a specific place or position. In the case of the National Address Register (NAR), the location is synonymous with a physical building. The address can be defined as the particulars of the location where someone lives or an organization is situated. In the case of the NAR, the address corresponds to "building units." Each location (building) has at least one address (building unit). For example, a single home will have one location and one physical address. An apartment or office building would have one location and several addresses for each building unit. A single home would be a one-to-one relationship and an apartment building would be a one-to-many relationship.
Example 1
A single home (single dwelling or building unit) with one address, 1 MAIN ST, TORONTO, ON M1M1A1, would have one unique locationId and one unique addressId (1:1 relationship).
1 MAIN ST, TORONTO, ON M1M1A1
locationId: 12345678-1234-1234-1234-123456789abc
addressId: 12345678-1234-1234-1234-123456789Bbc
Example 2
An office building that has multiple floors and units or suites at location 123 MAIN ST, TORONTO, ON M2M1A1 would have one unique locationId and many unique addressIds (1:n relationship). Each "building unit" would have its own address differentiated by the unit or suite number.
- 2-123 MAIN ST, TORONTO, ON M2M1A1
locationId: 22345678-1234-1234-1234-123456789abc
addressId: 22345678-1234-1234-1234-123456789Zbc - 4-123 MAIN ST, TORONTO, ON M2M1A1
locationId: 22345678-1234-1234-1234-123456789abc
addressId: 22345678-1234-1234-1234-123456789Ybc - 5-123 MAIN ST, TORONTO, ON M2M1A1
locationId: 22345678-1234-1234-1234-123456789abc
addressId: 22345678-1234-1234-1234-123456789Xbc - 8-123 MAIN ST, TORONTO, ON M2M1A1
locationId: 22345678-1234-1234-1234-123456789abc
addressId: 22345678-1234-1234-1234-123456789Rbc
Example 3
Address that uses all properties and attributes:
12-123 A MAIN ST N, OTTAWA, ON A0A 0A0
NAR attributes
| Attributes | Object | Description |
|---|---|---|
| locationId | Globally unique identifier for location | |
| addressId | Globally unique identifier for address | |
| civicNumber.prefix | Apartment or suite number | |
| civicNumber.number | Civic number | |
| civicNumber.suffix | Civic number suffix | |
| streetName | Official street name | |
| streetType | Official street designator | |
| streetDirection | Official street direction | |
| province | Province code | |
| cityName.en | Census subdivision English name | |
| cityName.fr | Census subdivision French name | |
| mailingAddress.streetName | Mailing street name | |
| mailingAddress.streetType | Mailing street designator | |
| mailingAddress.streetDirection | Mailing street direction | |
| mailingAddress.municipalityName | Mailing municipality name | |
| mailingAddress.province | Mailing province abbreviation | |
| mailingAddress.postalCode | Mailing postal code | |
| location.geographies[] | Array of geography classification objects associated with a location | |
| location.geographies[].{object} | Code | Federal electoral district, economic region, census subdivision code in specific array |
| Name.En | Federal electoral district, economic region, census subdivision English name in specific array | |
| Name.Fr | Federal electoral district, economic region, census subdivision French name in specific array | |
| location.geoCoordinates.latitude | Latitude coordinate | |
| location.geoCoordinates.longitude | Longitude coordinate | |
| building.dominionLandSurvey.quarter | Dominion Land Survey coordinate - Quarter | |
| building.dominionLandSurvey.section | Dominion Land Survey coordinate - Section | |
| building.dominionLandSurvey.town | Dominion Land Survey coordinate - Township | |
| building.dominionLandSurvey.range | Dominion Land Survey coordinate - Range | |
| building.dominionLandSurvey.meridian | Dominion Land Survey coordinate - Meridian | |
| building.dominionLandSurvey.x | Spatial X coordinate (GPS) of building | |
| building.dominionLandSurvey.y | Spatial Y coordinate (GPS) of building | |
| building.usage | Building Usage Codes | |
| building.additionalDeliveryInformation | Additional delivery information for mailing address (Ex: PO Box 432 or RR2 Site19 Box42) |
Useful links
- Canada Post addressing guidelines
- Government of Canada Standards on APIs
- HTTP Status Codes
- Open Data
- Statistics Canada Open Licence
- Standard Geographical Classification (SGC)
- Census Program
- Census Reference
- Directory, Census of population
- Census Reference
- OpenAPI (Swagger)
- Quarter Section Township Range Meridian (QSTRM) Information
Appendix
Codesets
HTTP status code list
The National Address Register (NAR) is a RESTful (using representational state transfer [REST] architecture) Application Programming Interface (API) that uses standard HTTP status codes to convey the results of a client's request in an API.
The status codes for NAR can be seen here.
| Code | Status | ResponseStatusCode description |
|---|---|---|
| 2XX | Success | This indicates that the client's request was accepted successfully. |
| 4XX | Client error | This category of status codes indicates the error is coming from the client side. |
| 5XX | Server error | The server takes responsibility for these error status codes. |
| 2XX codes | Description |
|---|---|
| 200 (ok) | The body contains the response object (metadata, search object, data object). |
| 204 (no content) | The server has fulfilled the request but does not need to return a response body. The server may return the updated meta information. |
| 4XX codes | Description |
|---|---|
| 400 (bad request) | The request could not be understood by the server because of incorrect syntax. The client should not repeat the request without modifications.
|
| 401 (unauthorized) | This indicates that the request requires user authentication information. The client may repeat the request with a suitable authorization header field. Example: User calls the API without using their API Key. |
| 403 (forbidden) | Unauthorized request: The client does not have access rights to the content. Unlike 401, the client's identity is known to the server. |
| 404 (not found) | The server cannot find the requested resource, when searching for an address, location, geography with a globally unique identifier (GUID) or code. |
| 5XX codes | Description |
|---|---|
| 500 (internal server error) | The server encountered an unexpected condition that prevented it from fulfilling the request. |
| 501 (not implemented) | A user tried to access a feature that is not implemented. |
Census Subdivision (CSD) Types
Census Subdivision (CSD) Types (CSDs) are classified into 57 types according to official designations adopted by provincial, territorial or federal authorities. Two exceptions are 'subdivision of unorganized' (SNO) in Newfoundland and Labrador, and 'subdivision of county municipality' (SC) in Nova Scotia, which are geographic areas created as equivalents for municipalities by Statistics Canada, in cooperation with those provinces, for the purpose of disseminating statistical data.
Table 1.5 shows CSD types, their abbreviated forms, and their provincial.
Geographies
Standard Geographical Classification (SGC)
Building Usage Codes
| Code | Description_English | Description_Français |
|---|---|---|
| 1 | Residential | Résidentiel |
| 2 | Partial Residential | Résidentiel partiel |
| 3 | Non Residential | Non résidentiel |
| 4 | Unknown | Inconnu |
Provinces
| Province Code | Province Abbreviation | Description_English | Description_Français |
|---|---|---|---|
| 10 | NL | Newfoundland and Labrador | Terre-Neuve-et-Labrador |
| 11 | PE | Prince Edward Island | Île-du-Prince-Édouard |
| 12 | NS | Nova Scotia | Nouvelle-Écosse |
| 13 | NB | New Brunswick | Nouveau-Brunswick |
| 24 | QC | Quebec | Québec |
| 35 | ON | Ontario | Ontario |
| 46 | MB | Manitoba | Manitoba |
| 47 | SK | Saskatchewan | Saskatchewan |
| 48 | AB | Alberta | Alberta |
| 59 | BC | British Columbia | Colombie-Britannique |
| 60 | YT | Yukon | Yukon |
| 61 | NT | Northwest Territories | Territoires du Nord-Ouest |
| 62 | NU | Nunavut | Nunavut |
Canada Post Symbols and abbreviations
Street types, Street directions, Provinces and territories
Contact information
Feedback and suggestions are welcome to improve and expand the use of the NAR, as well as questions or concerns. Please contact us at the following email address: statcan.statisticalregistersinfo-inforegistresstatistiques.statcan@statcan.gc.ca.
- Date modified: