> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.emtelligent.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.emtelligent.com/_mcp/server.

# Heading locations

Heading locations are used for identifying headings that identify sections.

Example NLP API result file:

* headings.json
* headings.txt

Specifically, the following snuppet contains an example of the new "headings" field.

```javascript
"locations": {
  "sections": [
    {
      "label": "SEC-1",
      "spans": [
        {
          "start": 0,
          "end": 45
        }
      ],
      "name": "ALLERGIES",
      "level": 0,
      "parent": null,
      "heading": "H0",
      "text": [
        "Allergies:\nLYRICA 75 MG CAPSULE - DEPRESSION\n"
      ]
    }
  ],
  ...,
  "headings": [
    {
      "label": "H0",
      "spans": [
        {
          "start": 0,
          "end": 9
        }
      ],
      "section": "SEC-1",
      "text": [
        "Allergies"
      ]
    }
  ]
```

## Changes

### Python API

The new heading location is available in `locations` under the `"heading"` key which contains instances of [HeadingLocation](/nlp/python/reference/data#emtelliprodataheadinglocation). There is also a link from sections using [heading](/nlp/python/reference/data#sectionlocationheading).

Example usage:

```python
import json
import pathlib
from emtellipro.data import AnnotatedDocument

json_data = pathlib.Path(sys.argv[1]).read_text()
doc_dict = json.loads(json_data)['documents'][0]
ann_doc = AnnotatedDocument(doc_dict)

print("Sections:")
for section in ann_doc.locations['section']:
    print(section.name, section.heading.text)

print()
print("Headings:")
for heading in ann_doc.locations['heading']:
    print(heading.text)
```

**`Output of previous code.`**

```text title="Output of previous code."
Sections:
ALLERGIES ['Allergies']

Headings:
['Allergies']
```

### Schema changes

The heading location is supported using the `headinglocation` and `headinglocationspan` tables.

#### Heading location

Schema of the new `headinglocation` table (in PostgreSQL):

```text
                                   Table "public.headinglocation"
       Column        |  Type   | Collation | Nullable |                   Default
---------------------+---------+-----------+----------+---------------------------------------------
 id                  | integer |           | not null | nextval('headinglocation_id_seq'::regclass)
 text                | text    |           |          |
 section_location_id | integer |           |          |
Indexes:
    "pk_headinglocation" PRIMARY KEY, btree (id)
Foreign-key constraints:
    "fk_headinglocation_section_location_id_sectionlocation" FOREIGN KEY (section_location_id) REFERENCES sectionlocation(id)
Referenced by:
    TABLE "headinglocationspan" CONSTRAINT "fk_headinglocationspan_heading_location_id_headinglocation" FOREIGN KEY (heading_location_id) REFERENCES headinglocation(id)
```

Example of data that is in that table:

```text
testdb=# select * from headinglocation;
 id | text | section_location_id
----+------+---------------------
  1 |      |                   1
(1 row)
```

Note that the link to the heading is done through `headinglocation.section_location_id`.

Linking to the document is done through the same `location` table as usual, but with `type_ = 'heading'`:

```text
testdb=# select * from location where type_ = 'heading';
 id |  type_  | document_id | location_id
----+---------+-------------+-------------
  2 | heading |           1 |           1
(1 row)
```

#### Heading location span

Schema of the new `headinglocationspan` table:

```text
                                   Table "public.headinglocationspan"
       Column        |  Type   | Collation | Nullable |                     Default
---------------------+---------+-----------+----------+-------------------------------------------------
 id                  | integer |           | not null | nextval('headinglocationspan_id_seq'::regclass)
 start               | integer |           |          |
 end                 | integer |           |          |
 heading_location_id | integer |           |          |
Indexes:
    "pk_headinglocationspan" PRIMARY KEY, btree (id)
Foreign-key constraints:
    "fk_headinglocationspan_heading_location_id_headinglocation" FOREIGN KEY (heading_location_id) REFERENCES headinglocation(id)
```

The two tables can be joined:

```text
   testdb=# select * from headinglocation join headinglocationspan on headinglocation.id = headinglocationspan.heading_location_id;
 id | text | section_location_id | id | start | end | heading_location_id
----+------+---------------------+----+-------+-----+---------------------
  1 |      |                   1 |  1 |     0 |   9 |                   1
(1 row)
```