> For the complete documentation index, see [llms.txt](https://docs.annolab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.annolab.ai/search/search-land-abstract.md).

# Search Land Abstract

Search a Land Abstract and return the Land Instruments it contains

## Search an abstract for land instruments

<mark style="color:blue;">`POST`</mark> `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<mark style="color:red;">\*</mark> | String | <p>API key authentication. The key must have the <code>read:all</code> scope, and its owner must have permission to export the project.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |
| Content-Type                                    | String | Must be `application/json`.                                                                                                                                                                                      |

#### Request Body

| Name                                                 | Type              | Description                                                                                             |
| ---------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------- |
| projectIdentifier<mark style="color:red;">\*</mark>  | 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<mark style="color:red;">\*</mark> | 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

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

{% tabs %}
{% tab title="200: Search results" %}

```json
{
  "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"
        }
      ]
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Search Result Object

| Attribute Name | Type                                                                                        | Description                                   |
| -------------- | ------------------------------------------------------------------------------------------- | --------------------------------------------- |
| page           | Number                                                                                      | Page number returned.                         |
| hasMorePages   | Boolean                                                                                     | Whether another page of results is available. |
| results        | [LandInstrumentJson](https://docs.annolab.ai/annotations-and-relations/land-instruments)\[] | 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.                |

{% tabs %}
{% tab title="Python" %}

```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}"
)
```

{% endtab %}
{% endtabs %}