Models

The objects a pipeline returns. You never construct these yourself — they come back from Geoparser.parse() and Project.get_documents() — so only the attributes you read are documented here.

Document

class Document

One text that was parsed.

text: str

The full text content of the document, as stored. Line endings are normalized to \n when the document is created, which matters when matching annotations against it by text.

id: uuid.UUID

The document’s unique identifier. These are the values returned by Project.create_documents() and accepted by the ids argument of Project.get_documents(). Store them alongside your own records to relate results back to where the text came from.

toponyms: List[Reference]

The place names found in this document: the references produced by the recognizer registered for the current tag.

Because it is filtered by tag, this is empty when no recognizer has been run under the tag you retrieved the document with — which is a different situation from a recognizer that ran and found nothing, though they look the same. See Managing Projects.

Reference

class Reference

One recognized place name within a document — a toponym. Obtained from Document.toponyms.

text: str | None

The place name as it appears in the document. Derived from the document text using start and end rather than stored independently, so it always reflects the offsets.

start: int

Character offset in the document text where the place name begins.

end: int

Character offset where the place name ends, exclusive — so document.text[reference.start:reference.end] is the place name. Widen the slice to recover the surrounding context.

location: Feature | None

The gazetteer feature this place name was resolved to by the resolver registered for the current tag, or None if it was not resolved.

None is a normal outcome: the place may be absent from the gazetteer, or no candidate may have passed the resolver’s confidence threshold. Always check before reading attributes.

Feature

class Feature

One place in a gazetteer. Returned by Reference.location, and by Gazetteer.search() and Gazetteer.find().

Two features are equal when they have the same identifier in the same gazetteer, so they can be used as dictionary keys or set members to aggregate mentions by place.

identifier: str

The feature’s stable identifier within its gazetteer — the geonameid for GeoNames, a UUID for SwissNames3D, whatever a custom gazetteer defines. This is what to store when recording a resolution, and what to group by when counting mentions per place: names are ambiguous, identifiers are not.

data: Dict[str, Any]

The feature’s attributes.

Which keys exist depends on the gazetteer, and on the source within it, so read them with .get() rather than by subscripting. For GeoNames, common keys are name, latitude, longitude, country_name, feature_name, feature_class, and population; for SwissNames3D, NAME, OBJEKTART, KANTON_NAME, and HOEHE. Full lists are in Querying Gazetteers. Cached after first access.

geometry: shapely.geometry.base.BaseGeometry | None

The feature’s geometry as a Shapely object, in the coordinate reference system given by crs — usually a point, but lines, polygons, and multi-part geometries occur.

None when the gazetteer records the place by name without locating it — roughly a sixth of Pleiades places, for instance, are attested in texts but never located. Cached after first access.

crs: str

The coordinate reference system geometry is expressed in, as an authority code such as EPSG:4326. Fixed per gazetteer and chosen when it is built, so every feature from one gazetteer shares it. Use this rather than assuming, when exporting spatial data from a custom gazetteer.

names: List[str]

Every name the feature is searchable by: its main name plus any historical spellings, transliterations, translations, and abbreviations the gazetteer records. Unordered and unlabelled — there is no notion of a preferred name or of a name’s language. Cached after first access.

source: str

The gazetteer source this feature was built from, such as allCountries for GeoNames. Useful for telling apart features of different kinds within one gazetteer, since attributes vary by source.