The BCLaws API
Spencer Tickner, Director Queen’s Printer
BCLaws (www.bclaws.ca) is a comprehensive research tool for legislative content in the Province of British Columbia, managed and maintained by the Queen’s Printer.
Did you know that BCLaws is also built on an open Application Programming Interface (API) which allows you to interact with this legislative information in granular and data centric ways? By knowing a bit about the URL structure, you can consume and embed legislative data in applications or webpages.
For this blog, let’s pretend that you are a policy analyst working on a landlord and tenant policy that will be published on the internet.
Legislation as Data
This particular policy that you are developing will have many references to the Residential Tenancy Act. The Residential Tenancy Act can be found on BCLaws at the following address:
In the past we could always link to the act, but it brings our readers out of context and interrupts the flow of our well written policy. Luckily, we know about the BCLaws API and can use it to enhance our readers’ experience.
When using the API, we can see the act as the data that drives the HTML representation by adding “/xml” to the end of the URL. You can try it yourself by simply adding “/xml” to the end of the url or by clicking on the following link:
What you are now seeing is the XML representation of the Residential Tenancy Act. Although not as easy on the human eye, this is the data that we can now start to use in an exciting ways.
Walking the Tree
The data that is returned from the API is in a very structured format called XML. This structure gives us a way to walk the “tree” to granular areas of the document that we may be interested in:
XML acts like a folder structure or tree with elements being nested within other elements. Because of the structured nature of XML we can specifically target any data within that structure with a “path”, much like you can reference any file on your computer with a file “path”. In our case we want to reference the definition for “approved form” in our policy. I’ve highlighted each “level” along the path, and again like the folder structure on our computer we can walk the path like so:
/act:act/act:content/bcl:part/bcl:division/bcl:section/bcl:definition[@id = ‘d2e65’]
Because we only want to look at this exact definition we use the id attribute and specify the unique identifier d2e65 that applies to the “approved form” definition.
This is an actual language for traversing XML documents called XPath. More information on the language can be found at W3C School
So let’s put it all together.
- Start with the URL for the Act you wish to reference. In this case the Residential Tenancy Act:
- Next, we tell the BCLaws API that we are going to limit the data we want returned by using the key word xpath (similar to before when we requested XML from the BCLaws API):
- Finally we use the xpath expression we created to bring back only the data from the document that we specify:
- /act:act/act:content/bcl:part/bcl:division/bcl:section/bcl:definition[@id = ‘d2e65’]
So, the final URL for extracting the “approved form” definition from the act is as follows:
Reference Multiple Data Points
Using the xpath API you can reference any data point of legislation in this way. You can also reference multiple data points. XPath uses the pipe operator “|” to make multiple expressions. For instance, in our example above we have now decided that we would also like to capture the title of the document so that the reader has more context for what they are reading. Again we “walk” our tree to create an xpath to the title element:
We then add this path to the end of our expanding URL using the pipe operator:
As you can see, by clicking on the above link we now get both the definition for “approved form” and the title of the act “Residential Tenancy Act”
Example Policy Document:
Because we are writing this policy for the web, we can then embed this information directly in our policy document using an iframe. The following code would embed the work we’ve done inline into our policy document:
And finally below is a sample fictitious policy that displays this. Not only is the reader’s attention not taken out of the focus of the document, but if the definition for “approved form” or the title of the “Residential Tenancy Act” ever changes, those changes will be pulled in real time through the API and the policy document will be updated automatically:
Conflict Resolution Documentation (Example, Not Real)
When working through conflict resolution process between a tenant and landlord there must be a signed form stating the approval of both parties to enter into the process. That form must meet the requirements of legislation in British Columbia:
|act:act/act:title” title=”Definition of Approved Form” width=”100%” height=”270″]
We hope this simple example has shown how you can add value to your documents by leveraging the BCLaws API.
There are many other possible uses of the API including building whole new legislative websites that pull BCLaws data to create new legislative research tools.
If you are interested in learning more about the various API calls that you can make, you can find more comprehensive documentation on the API via the BC Data Catalogue BC Laws API entry.