The Document API allows you to retrieve actual documents from a library 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/
<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>
</root>
In this example we will retrieve the Drinking Water Protection Act. Its 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 CiviX Server API can be accessed in this way
Many of the legislative documents available through the CiviX Server API are in XML format. If a document is available in XML the BCLaws API is able to give enhances API functionality for consuming the information. For the following examples we will user the Drinking Waster Protection Act mentioned above.
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.
http://www.bclaws.ca/civix/document/id/complete/statreg/01009_01/xml would return the following:
<?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 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":
<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>
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 retieve snippets from the document.
For instance in the following example we will just retrieve the definition that defines the 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 documnet
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.
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
Finally if we then want to view only the sections that contain the phrase "protection plan" in an xml format we can compine all the Document API techniques in the following way
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:
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.
A full schema definition for Acts can be found here.
A full schema definition for Regulations can be found here.
A full schema definition for Bylaws can be found here.
XSLT is a processing language to convert XML to other formats or structure. The following XSLT are available for converting documents using the above XSD definitions into HTML:
The XSLT for converting Acts from XML to HTML can be found here.
The XSLT for converting Regulations from XML to HTML can be found here.
The XSLT for converting Bylaws from XML to HTML can be found here.