Document

Overview

The Document API allows you to retrieve actual documents from the BCLaws legislative repository.

To retrieve a document from the repository you need two specific pieces of information: the index identifier and the document identifier. These unique identifiers can be retrieved from the Content API. As an example, the Content API returns the following XML snippet from http://www.bclaws.ca/civix/content/complete/statreg/1421132707/01009/

HTTP Example XML (Shortened for Brevity)


    <root>
        <document>
            <CIVIX_DOCUMENT_TITLE>Drinking Water Protection Act</CIVIX_DOCUMENT_TITLE>
            <CIVIX_DOCUMENT_LOC>-- D --/Drinking Water Protection Act [SBC 2001] c. 9/00_01009_01.xml</CIVIX_DOCUMENT_LOC>
            <CIVIX_DOCUMENT_ID>01009_01</CIVIX_DOCUMENT_ID>
            <CIVIX_INDEX_ID>statreg</CIVIX_INDEX_ID>
            <CIVIX_DOCUMENT_INDEX>true</CIVIX_DOCUMENT_INDEX>
            <CIVIX_DOCUMENT_TYPE>document</CIVIX_DOCUMENT_TYPE>
            <CIVIX_DOCUMENT_PARENT>01009</CIVIX_DOCUMENT_PARENT>
            <CIVIX_DOCUMENT_ANCESTORS>01009</CIVIX_DOCUMENT_ANCESTORS>
            <CIVIX_DOCUMENT_ANCESTORS>1421132707</CIVIX_DOCUMENT_ANCESTORS>
            <CIVIX_DOCUMENT_ANCESTORS>statreg</CIVIX_DOCUMENT_ANCESTORS>
            <CIVIX_DOCUMENT_VISIBLE>true</CIVIX_DOCUMENT_VISIBLE>
            <CIVIX_DOCUMENT_MATERIAL>000000007691000104</CIVIX_DOCUMENT_MATERIAL>
        </document>

In this example we will retrieve the Drinking Water Protection Act. It's unique document identifier (CIVIX_DOCUMENT_ID) is 01009_01. The unique identifer for the index that it belongs to is statreg (CIVIX_INDEX_ID) and by combining these two pieces of information with the aspect identifier complete (See Content API) you can retrieve the document using the following url http://www.bclaws.ca/civix/document/id/complete/statreg/01009_01.

Any document within the BCLaws library can be accessed in this way

XML Documents

Many of the legislative documents available through the BCLaws API are in XML format. If a document is available in XML, the BCLaws API is able to give enhanced functionality for consuming the information. For the following examples we will use the Drinking Water Protection Act mentioned above.

Retrieving XML vs HTML

By default XML documents are transformed into HTML for viewing. If you are interested in accessing the XML content, the keyword XML can be appended to the document id link mentioned above.

Example Document URL

http://www.bclaws.ca/civix/document/id/complete/statreg/01009_01/xml would return the following:

HTTP Example XML (Shortened for Brevity)


    <?xml version="1.0" encoding="UTF-8"?>
    <act:act xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    	xmlns:act="http://www.gov.bc.ca/2013/legislation/act" 
    	xmlns:bcl="http://www.gov.bc.ca/2013/bclegislation" 
        xmlns:xlink="http://www.w3.org/1999/xlink"
        xmlns:in="http://www.qp.gov.bc.ca/2013/inline" 
        xmlns:fun="http://www.bclaws.ca/xslt/functions" 
        xmlns:oasis="http://docs.oasis-open.org/ns/oasis-exchange/table" 
        xmlns:reg="http://www.gov.bc.ca/2013/legislation/regulation"
        xsi:schemaLocation="http://www.gov.bc.ca/2013/legislation/act 
        	http://standards.qp.gov.bc.ca/standards/act.xsd" 
        id="00_01009_01">
        <act:title>Drinking Water Protection Act</act:title>
        <act:chapter>9</act:chapter>
        <act:yearenacted>2001</act:yearenacted>
        <act:currency>
            <act:tlc>E3tlc01009</act:tlc>
        </act:currency>
        <act:assentedto>April 11, 2001</act:assentedto>
        <act:content>
            <bcl:part id="d2e25">
                <bcl:num>1</bcl:num>
                <bcl:text>Introductory Provisions</bcl:text>
                <bcl:section id="d2e34">
                    <bcl:marginalnote>Definitions</bcl:marginalnote>
                    <bcl:num>1</bcl:num>
                    <bcl:text>In this Act:</bcl:text>
                    <bcl:definition id="d2e45">
                        <bcl:text>
                            <bcl:term>aquifer</bcl:term>means an aquifer as defined in the 
                            <bcl:link resource="leg" xlink:href="/legislation/96483_01" xlink:type="locator"><in:doc>Water 
                            Act</in:doc></bcl:link>;</bcl:text>
                    </bcl:definition>

Multi documents

Multi documents are documents large enough in size to warrant being split into multiple parts. This can be evidenced by finding documents with an html table of contents within a directory. The Business Corporations Act [SBC 2002] is such an example:

http://www.bclaws.ca/civix/content/complete/statreg/1944036832/02057/472785307/?xsl=/templates/browse.xsl

To retrieve the original complete XML document you can take the ID of the table of contents, and append "_multi". For example, the aforementioned Business Corporations Act [SBC 2002] has a table of contents with the ID: 02057_00. To retrieve the full xml document use the ID: 02057_00_multi.

The full document will be listed within the markup with CIVIX_DOCUMENT_VISIBLE and CIVIX_DOCUMENT_INDEX both set to false:

HTTP Example XML (Shortened for Brevity)

	<document>
		<CIVIX_DOCUMENT_TITLE>Business Corporations Act</CIVIX_DOCUMENT_TITLE>
		<CIVIX_DOCUMENT_LOC>-- B --/Business Corporations Act [SBC 2002] c. 57/00_Act/hidden_00_02057_multi.xml</CIVIX_DOCUMENT_LOC>
		<CIVIX_DOCUMENT_ID>02057_00</CIVIX_DOCUMENT_ID>
		<CIVIX_INDEX_ID>statreg</CIVIX_INDEX_ID>
		<CIVIX_DOCUMENT_INDEX>false</CIVIX_DOCUMENT_INDEX>
		<CIVIX_DOCUMENT_TYPE>document</CIVIX_DOCUMENT_TYPE>
		<CIVIX_DOCUMENT_PARENT>472785307</CIVIX_DOCUMENT_PARENT>
		<CIVIX_DOCUMENT_ANCESTORS>472785307</CIVIX_DOCUMENT_ANCESTORS>
		<CIVIX_DOCUMENT_ANCESTORS>02057</CIVIX_DOCUMENT_ANCESTORS>
		<CIVIX_DOCUMENT_ANCESTORS>1944036832</CIVIX_DOCUMENT_ANCESTORS>
		<CIVIX_DOCUMENT_ANCESTORS>statreg</CIVIX_DOCUMENT_ANCESTORS>
		<CIVIX_DOCUMENT_ANCESTORS>02057_00</CIVIX_DOCUMENT_ANCESTORS>
		<CIVIX_DOCUMENT_VISIBLE>false</CIVIX_DOCUMENT_VISIBLE>
		<CIVIX_DOCUMENT_ORDER>80</CIVIX_DOCUMENT_ORDER>
	</document>

Navigating the document with XPath

XPath is a language for navigating XML documents. XPath syntax is out of scope of this document but there is a good tutorial at W3C Schools.

By using the XPath API, users can consume xml documents in a much more granular way.

By appending /xpath/ to the document id url above, then appending a valid xpath expression, you can retrieve snippets from the document.

Example

For instance, in the following example we will just retrieve the definition that defines the term local government.

http://www.bclaws.ca/civix/document/id/complete/statreg/01009_01/xpath///bcl:definition[bcl:text/in:term= 'local government']

The previous technique can also be combined with the extraction of information in xml by placing the XML keyword after the CIVIX_DOCUMENT_ID of the document.

http://www.bclaws.ca/civix/document/id/complete/statreg/01009_01/xml/xpath///bcl:definition[bcl:text/in:term= 'local government']

Adding Search to the document

Search terms may also be added to the url to highlight potential areas of interest. More on searching can be found in the Search API Documentation regarding site wide searches.

Example Document Search

At the document level, the keyword search and a search term can be appended to the url. In the following example we retrieve the Drinking Water Protection Act with the phrase "protection plan" highlighted.

www.bclaws.ca/civix/document/id/complete/statreg/01009_01/search/"protection plan"

If the document is of an XML type we can then begin to layer on the Document functionality by using the other techniques above. For instance, let's say that we wanted to see only the sections that contain the phrase "protection plan" we can combine the search and xpath API capabilities in the following way:

Example Search and XPath

http://www.bclaws.ca/civix/document/id/complete/statreg/01009_01/search/"protection plan"/xpath///bcl:section[descendant::hit]

If we would then want to view only the sections that contain the phrase "protection plan" in an xml format we can combine all the Document API techniques in the following way:

Example Search and XPath return XML

http://www.bclaws.ca/civix/document/id/complete/statreg/01009_01/xml/search/"protection plan"/xpath///bcl:section[descendant::hit]

Document API ordering

Just a note of caution that although these techniques can be combined to produce interesting, granular results, the order within the url is important. When combining the calls from left to right the order must be:

XML Definitions

We provide Schemas to give API consumers an idea of what XML structure to expect when interacting with Legislative XML documents

XSD Schema syntax is out of scope of this document but there is a good tutorial at W3C Schools.

Note: These Schemas are being finalized and all documents may not validate at this time.

A full schema definition for Acts can be found here.

A full schema definition for regulations can be found here.