Knowledge Bases

Use knowledge bases to find legal information related to a query.

What are Knowledge Bases?

A Knowledge Base (KB) is a database of legal information stored using an embedding database. You can use the retrieve API to query the Knowledge Base for items of legal data that match a query.

Our legislation Knowledge Bases contain the full text of all the digitised legislation that is available through the Laws.Africa Content API. The legislation is split into portions (chapters, sections, paragraphs, etc.) and embeddings are calculated for each portion. These embeddings make it possible to perform semantic queries against the data to find portions relevant to a keyword, phrase or question.

Knowledge Bases include only the most recent version of legislation. See Works and Expressions for more details on how legislation changes over time.

List available Knowledge Bases

Explore legal data Knowledge Bases for use with Generative AI (PREVIEW).

Get details of Laws.Africa's Knowledge Bases.

Note: this API is a preview and may change in future.

GET/ai/v1/knowledge-bases

Authorization

cookieAuthtokenAuth

Query parameters

Response

200

Body

application/json

countinteger

Example: 123

nextnullable string

previousnullable string

resultsarray of KnowledgeBase (object)

Request

JavaScriptCurlPython

const response = await fetch('/ai/v1/knowledge-bases', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "count": 123,
  "next": "text",
  "previous": "text",
  "results": [
    {
      "code": "text",
      "name": "text",
      "description": "text",
      "url": "https://example.com"
    }
  ]
}

Get details of a single knowledge base

Explore legal data Knowledge Bases for use with Generative AI (PREVIEW).

Get details of Laws.Africa's Knowledge Bases.

Note: this API is a preview and may change in future.

GET/ai/v1/knowledge-bases/{code}

Authorization

cookieAuthtokenAuth

Path parameters

code*string

Unique code identifying this knowledge base

Response

200

Body

application/json

code*string

Unique code identifying this knowledge base

Pattern: ^[-a-zA-Z0-9_]+$

name*string

Name of the knowledge base

description*string

Description of the knowledge base

url*string (uri)

Request

JavaScriptCurlPython

const response = await fetch('/ai/v1/knowledge-bases/{code}', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

{
  "code": "text",
  "name": "text",
  "description": "text",
  "url": "https://example.com"
}

Query a Knowledge Base

Use the retrieve API to query a Knowledge Base for information matching keywords or phrases.

When you query a knowledge base, you must submit a POST request:

1. Identify the Knowledge Base to query using its code in the URL of the request.

2. Specify the text to search the Knowledge Base for using the text parameter.

The API will return matching items (portions of legislation) that match your query, including a score, the text of the portion, and metadata.

Query the knowledge base for matching items.

Retrieve items from the knowledge base that match your query.

POST/ai/v1/knowledge-bases/{code}/retrieve

Authorization

cookieAuthtokenAuth

Path parameters

code*string

Unique code identifying this knowledge base

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

text*string

The text to find matching items for

top_kinteger

Number of results to return

Response

200

Body

application/json

results*array of KnowledgeBaseItem (object)

Request

JavaScriptCurlPython

const response = await fetch('/ai/v1/knowledge-bases/{code}/retrieve', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "text": "text"
    }),
});
const data = await response.json();

Response

200

{
  "results": [
    {
      "content": {
        "text": "text"
      },
      "score": 0
    }
  ]
}

Result item information

The API returns the text of the matching item, the score of the match (a lower score is better), and metadata for the portion. This provides very precise details on the portion of legislation that matched the query, allowing you to provide concrete citation information to your user.

The metadata includes a combination of:

1. Details of the legislative work, including FRBR URI information.

2. Table of Contents information for the portion of that work.

For example:

{
  "metadata": {
    "portion_id": "chp_2__sec_2",
    "frbr_locality": "jhb",
    "portion_num": "2.",
    "portion_title": "2. Restriction on number of dogs",
    "frbr_place": "za-jhb",
    "title": "Dogs and Cats",
    "expression_date": "2019-09-04",
    "portion_frbr_uri": "/akn/za-jhb/act/by-law/2006/dogs-and-cats/eng/~chp_2__sec_2",
    "work_frbr_uri": "/akn/za-jhb/act/by-law/2006/dogs-and-cats",
    "portion_heading": "Restriction on number of dogs",
    "frbr_country": "za",
    "portion_type": "section"
  }
}