Models

Document

class Document(*, text: ~typing.Annotated[str, ~pydantic.functional_validators.AfterValidator(func=~geoparser.db.models.validators.normalize_newlines)], id: ~uuid.UUID = <factory>, project_id: ~uuid.UUID)

Bases: DocumentBase

Represents a document to be processed for reference recognition and resolution.

A document belongs to a project and can contain multiple references.

The Document model represents a text document that has been added to a project for geoparsing.

Properties:

text: str: The full text content of the document.

toponyms: List[Reference]: Returns references (identified place names) filtered by the recognizer configured in the current context. This property is used to access the place names that were identified by a specific recognizer module.

Reference

class Reference(*, start: int, end: int, text: str | None = None, id: ~uuid.UUID = <factory>, document_id: ~uuid.UUID, recognizer_id: str)

Bases: ReferenceBase

Represents a reference (place name) identified in a document.

A reference is a place name found in text, defined by its start and end positions. It can have multiple potential referent interpretations (resolved referents).

The Reference model represents an identified place name (toponym) within a document.

Properties:

start: int: The starting character position of the place name in the document text.

end: int: The ending character position of the place name in the document text.

text: str | None: The actual text of the place name as it appears in the document. This is typically extracted automatically from the document text using the start and end positions.

location: Feature | None: Returns the resolved geographic feature from the resolver configured in the current context. This property provides access to the geographic entity that this place name refers to, or None if the place name could not be resolved.

Feature

class Feature(*, location_id_value: str, id: int, source_id: int)

Bases: FeatureBase

Represents a feature from a gazetteer.

A feature is a unique geographic entity in a gazetteer, identified by a specific identifier within that gazetteer’s table structure.

The Feature model represents a geographic entity from a gazetteer.

Properties:

data: Dict[str, Any] | None: Returns the complete gazetteer row data for this feature as a dictionary. The available attributes depend on which gazetteer the feature comes from. For GeoNames, common attributes include name, latitude, longitude, country_name, feature_name, population, and administrative divisions. For SwissNames3D, attributes include NAME, OBJEKTART, GEMEINDE_NAME, KANTON_NAME, and elevation. This property is cached for performance.

geometry: BaseGeometry | None: Returns the geographic geometry (point, line, or polygon) associated with this feature as a Shapely geometry object. This property is cached for performance.