National Address Register - User Guide

October 27, 2021

Version 1.0 Produced by: Data Integration Infrastructure Division

Contents

Contents

Revision history

Revision History
Date Version Revision details
October 27, 2021 1.0 First release of NAR User Guide

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. 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 100.

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:

Addresses

  • GetAddresses
  • GetAddressesByGUID
  • SearchAddresses

Locations

  • GetLocations
  • GetLocationsByGUID

Geographies

  • GetCensusSubDivisions
  • GetCensusSubDivisionsByCode
  • GetEconomicRegions
  • GetEconomicRegionsByCode
  • GetFederalElectoralDistricts
  • GetFederalElectoralDistrictsByCode

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])

{
  "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"
          }
        ]
      }
    },
  ]
}

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:
228a72b8-3c1b-4734-b1cd-015490686513
/addresses/228a72b8-3c1b-4734-b1cd-015490686513

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)

{
  "meta": {
    "prepared": "",
    "test": false,
    "contentLanguage": [
      "en"
    ]
  },
  "search": {
    "searchStyle": "simple",
    "criteria": "",
    "total": 1
  },
  "data": [
    {
      "addressId": "228a72b8-3c1b-4734-b1cd-015490686513",
      "civicNumber": {
        "prefix": null,
        "number": "308",
        "suffix": {
          "code": null
        }
      },
      "streetName": "Moyer",
      "streetType": {
        "code": "RD"
      },
      "streetDirection": {
        "code": null
      },
      "cityName": {
        "en": "Kelowna"
      },
      "province": {
        "code": "59"
      },
      "country": {
        "code": "CA",
        "name": {
          "en": "Canada"
        }
      },
      "mailingAddress": {
        "streetName": "MOYER",
        "streetType": {
          "code": "RD"
        },
        "streetDirection": {
          "code": null
        },
        "municipalityName": "KELOWNA",
        "province": {
          "code": "BC"
        },
        "country": {
          "code": "CA",
          "name": {
            "en": "Canada"
          }
        },
        "postalCode": "V1X4R7"
      },
      "location": {
        "locationID": "520b316f-b2ec-41bf-8a64-0000000aa537",
        "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",
              "name": {
                "en": "Kelowna"
              }
            },
            "source": "CSD_2016",
            "geographicType": "CSD"
          }
        ]
      }
    }
  ]
}

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:
308 MOYER RD KELOWNA BC V1X4R7
/addresses/search?qstr=308%20MOYER%20RD%20KELOWNA%20BC%20V1X4R7

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)

{
  "meta": {
    "prepared": "",
    "test": false,
    "contentLanguage": [
      "en"
    ]
  },
  "search": {
    "searchStyle": "simple",
    "criteria": "Query: 308 MOYER RD KELOWNA BC V1X4R7  ",
    "total": 1
  },
  "data": [
    {
      "addressId": "228a72b8-3c1b-4734-b1cd-015490686513",
      "civicNumber": {
        "prefix": null,
        "number": "308",
        "suffix": {
          "code": null
        }
      },
      "streetName": "Moyer",
      "streetType": {
        "code": "RD"
      },
      "streetDirection": {
        "code": null
      },
      "cityName": {
        "en": "Kelowna"
      },
      "province": {
        "code": "59"
      },
      "country": {
        "code": "CA",
        "name": {
          "en": "Canada"
        }
      },
      "mailingAddress": {
        "streetName": "MOYER",
        "streetType": {
          "code": "RD"
        },
        "streetDirection": {
          "code": null
        },
        "municipalityName": "KELOWNA",
        "province": {
          "code": "BC"
        },
        "country": {
          "code": "CA",
          "name": {
            "en": "Canada"
          }
        },
        "postalCode": "V1X4R7"
      },
      "location": {
        "locationID": "520b316f-b2ec-41bf-8a64-0000000aa537",
        "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",
              "name": {
                "en": "Kelowna"
              }
            },
            "source": "CSD_2016",
            "geographicType": "CSD"
          }
        ]
      }
    }
  ]
}

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

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

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.

  1. 2-123 MAIN ST, TORONTO, ON M2M1A1
    locationId: 22345678-1234-1234-1234-123456789abc
    addressId: 22345678-1234-1234-1234-123456789Zbc
  2. 4-123 MAIN ST, TORONTO, ON M2M1A1
    locationId: 22345678-1234-1234-1234-123456789abc
    addressId: 22345678-1234-1234-1234-123456789Ybc
  3. 5-123 MAIN ST, TORONTO, ON M2M1A1
    locationId: 22345678-1234-1234-1234-123456789abc
    addressId: 22345678-1234-1234-1234-123456789Xbc
  4. 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

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

Useful links

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.

Status codes for NAR
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
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
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.
  • When a field name is erroneous: An entered field is not supported.
  • When an operator is unsupported: An entered operator is not supported.
  • When an erroneous operator is inserted: The syntax of the query was incorrect.
  • When attempting to use contains with a numeric value: The syntax of the query was incorrect.
  • When attempting to query with a string value that is not surrounded by double quotation marks: The string value is invalid. It must be surrounded by double quotation marks.
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
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)

Provinces

province codes
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: