Search Land Abstract

Search a Land Abstract and return the Land Instruments it contains

Search an abstract for land instruments

POST https://api.annolab.ai/v1/abstract/land/instruments/search

Returns the land instruments associated with one abstract, including the instrument's extracted recording data, parties, dates, page boundaries, and tract conveyances.

The response is paginated, returning up to 200 instruments at a time. Start with page 1, then request successive pages while hasMorePages is true.

Headers

Name	Type	Description
Authorization*	String	API key authentication. The key must have the read:all scope, and its owner must have permission to export the project. {"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}
Content-Type	String	Must be application/json.

Request Body

Name	Type	Description
projectIdentifier*	String | Integer	Either the name of the AnnoLab project or the the project ID.
groupName	String	Name of the group that owns the project. When omitted, the project is resolved for the API key's owner.
abstractIdentifier*	String | Integer	The name of the Abstract where search will be performed or the ID of the Abstract
page	Number	Page to return. Defaults to 1.

Example Request Body

{
  "projectIdentifier": "Permian Basin Title Project",
  "groupName": "Oil Company 1",
  "abstractIdentifier": "Reeves County Abstract 42",
  "page": 1
}

200: Search results

{
  "page": 1,
  "hasMorePages": false,
  "results": [
    {
      "subDocumentId": 10482,
      "startPageNumber": 3,
      "startPagePct": 0,
      "endPageNumber": 7,
      "endPagePct": 100,
      "sourceReferenceId": 615,
      "sourceReferenceName": "2024-001234.pdf",
      "instrumentType": "Mineral Deed",
      "comments": ["Legal description continues on Exhibit A"],
      "countyBookNumber": "182",
      "countyPageNumber": "417",
      "instrumentTitle": "Mineral Deed",
      "interestTypes": ["Minerals"],
      "grantorNames": ["Example Grantor, LLC"],
      "granteeNames": ["Example Grantee, LP"],
      "instrumentNumber": "2024-001234",
      "effectiveDate": "01/15/2024",
      "primaryTerm": "3 Years",
      "extensionTerm": "1 Year",
      "royaltyRate": "",
      "pughClause": "",
      "executedDate": "01/15/2024",
      "fileDate": "01/22/2024",
      "recordedDate": "01/22/2024",
      "referencedInstruments": [],
      "conveyances": [
        {
          "id": 78301,
          "county": "Reeves",
          "city": "",
          "section": "12",
          "township": "2S",
          "range": "",
          "legalBody": "NW/4",
          "subdivision": "",
          "lot": "",
          "block": "C-8",
          "grossAcres": "160",
          "well": "",
          "abstractId": "42",
          "survey": "Public School Land",
          "depthClause": "Pertaining only to the wolfcamp formation",
          "grantorLessor": ["Example Grantor, LLC"],
          "granteeLessee": "Example Grantee, LP",
          "grantingLanguage": "grants, sells, and conveys",
          "grantedPct": "1/3",
          "grantedBasis": "Entire",
          "interestTypes": ["minerals"],
          "pageNumber": "4",
          "statedNet": "3.25",
          "grantorDomainEntities": [
            {
              "name": "Example Grantor, LLC",
              "address": "100 Main Street, Midland, TX 79701"
            }
          ],
          "granteeDomainEntities": {
            "name": "Example Grantee, LP",
            "address": "200 Market Street, Houston, TX 77002"
          },
          "referenceInstruments": "Reeves-bk140-pg133-inst#1738"
        }
      ]
    }
  ]
}

Search Result Object

Attribute Name	Type	Description
page	Number	Page number returned.
hasMorePages	Boolean	Whether another page of results is available.
results	LandInstrumentJson[]	Land instruments in the abstract.

Errors

Status	Description
400 Bad Request	The request body is invalid, the project does not exist, or the abstract does not exist in the selected project.
401 Unauthorized	The API key is missing or invalid.
403 Forbidden	The API key lacks the required scope or its owner does not have permission to export the project.

Python

import json
from urllib.error import HTTPError
from urllib.request import Request, urlopen

ANNO_LAB_API_KEY = "XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX"
project = "TX Permian"
groupName = "Oil Company 1"
abstractName = "Section 1 - Blk 22 - Midland TX"
timeout = 120
output_file = "abstract-results.json"

url = "https://api.annolab.ai/v1/abstract/land/instruments/search"
headers = {
    "Authorization": f"Api-Key {ANNO_LAB_API_KEY}",
    "Content-Type": "application/json",
}
search_body = {
    "projectIdentifier": project,
    "groupName": groupName,
    "abstractIdentifier": abstractName,
    "page": 1,
}
all_results = []

while True:

    request = Request(
        url,
        data=json.dumps(search_body).encode(),
        headers=headers,
        method="POST",
    )

    try:
        with urlopen(request, timeout=timeout) as response:
            data = json.load(response)
    except HTTPError as error:
        print(error.read().decode())
        raise SystemExit(1)

    results = data["results"]
    all_results.extend(results)
    print(f"Page {data['page']}: {len(results)} results")

    if not data["hasMorePages"]:
        break

    search_body["page"] = data["page"] + 1


with open(output_file, "w") as file:
    json.dump(all_results, file, indent=2)

print(
    f"Total: {len(all_results)} from {abstractName} results written to {output_file}"
)