Metadata-Version: 2.4
Name: geoparser
Version: 0.6.0
Summary: A customizable geoparsing library for unstructured text
License: MIT
License-File: LICENSE
Author: Diego Gomes
Author-email: diego.gomes@uzh.ch
Requires-Python: >=3.10,<3.15
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: accelerate (>=1.11.0,<2.0.0)
Requires-Dist: appdirs (>=1.4.4,<2.0.0)
Requires-Dist: datasets (>=5.0.0,<6.0.0)
Requires-Dist: duckdb (>=1.5.4,<2.0.0)
Requires-Dist: fastapi (>=0.121.0,<0.122.0)
Requires-Dist: markupsafe (>=3.0.3,<4.0.0)
Requires-Dist: pydantic (>=2.12.3,<3.0.0)
Requires-Dist: pyproj (>=3.7.1,<4.0.0)
Requires-Dist: python-multipart (>=0.0.20,<0.0.21)
Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
Requires-Dist: rapidfuzz (>=3.14.5,<4.0.0)
Requires-Dist: requests (>=2.32.5,<3.0.0)
Requires-Dist: rich (>=15.0.0,<16.0.0)
Requires-Dist: sentence-transformers (>=5.1.2,<6.0.0)
Requires-Dist: shapely (>=2.1.2,<3.0.0)
Requires-Dist: spacy (>=3.8.7,<4.0.0,!=3.8.14)
Requires-Dist: sqlalchemy (>=2.0.44,<3.0.0)
Requires-Dist: sqlmodel (>=0.0.39,<0.0.40)
Requires-Dist: torch (>=2.9.0,<3.0.0)
Requires-Dist: transformers (>=5.0.0,<6.0.0)
Requires-Dist: typer (>=0.27.0,<0.28.0)
Requires-Dist: uvicorn (>=0.38.0,<0.39.0)
Requires-Dist: werkzeug (>=3.1.3,<4.0.0)
Project-URL: Homepage, https://geoparser.app
Project-URL: Repository, https://github.com/dguzh/geoparser
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/_static/logo.png" alt="Irchel Geoparser" width="360">
</p>

<p align="center">
  <a href="https://github.com/dguzh/geoparser/actions/workflows/test.yml?query=branch%3Amain+"><img src="https://img.shields.io/github/actions/workflow/status/dguzh/geoparser/test.yml?branch=main&logo=github&label=CI" alt="CI"></a>
  <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/dguzh/geoparser"><img src="https://coverage-badge.samuelcolvin.workers.dev/dguzh/geoparser.svg" alt="Coverage"></a>
  <a href="https://pypi.org/project/geoparser"><img src="https://img.shields.io/pypi/v/geoparser.svg" alt="PyPI"></a>
  <a href="https://pepy.tech/projects/geoparser"><img src="https://static.pepy.tech/badge/geoparser" alt="Downloads"></a>
  <a href="https://pypi.org/project/geoparser"><img src="https://img.shields.io/pypi/pyversions/geoparser.svg" alt="Python"></a>
  <a href="https://github.com/dguzh/geoparser/blob/main/LICENSE"><img src="https://img.shields.io/github/license/dguzh/geoparser.svg" alt="License"></a>
</p>

A Python library for extracting place names from text and linking them to geographic locations.

Geoparsing is split into two stages, and the library keeps them separate: a *recognizer* finds which words are place names, and a *resolver* decides which place each name refers to, choosing from the entries of a *gazetteer*. You supply the recognizer, the resolver, and the gazetteer explicitly, and each can be exchanged for another: a module can be replaced by one that works differently, pointed at a different underlying model, or fine-tuned on your own annotated data, and you can write a module of your own against a small interface. The library ships gazetteer configurations for the modern world and for Switzerland, and other geographic data becomes a gazetteer through a YAML configuration file, with no code to write.

## Installation

```bash
pip install geoparser
```

The library also needs a gazetteer, which is not bundled: it is the database of places that names are resolved against.

```bash
python -m geoparser install geonames
```

See the [installation guide](https://docs.geoparser.app/en/latest/installation.html) for environment setup, the available gazetteers, and their disk requirements.

## Quick Start

```python
from geoparser import Geoparser
from geoparser.modules import SentenceTransformerResolver, SpacyRecognizer

# Build a pipeline from a recognizer and a resolver
geoparser = Geoparser(
    recognizer=SpacyRecognizer(),
    resolver=SentenceTransformerResolver(gazetteer_name="geonames"),
)

# Parse text
document = geoparser.parse(
    "The conference was held in Zurich, with satellite events in Geneva and Basel."
)

# Access results
for toponym in document.toponyms:
    location = toponym.location  # None if the name could not be resolved
    print(f"{toponym.text} -> {location.data['name']}, {location.data['country_name']} "
          f"({location.data['latitude']}, {location.data['longitude']})")
```

```text
Zurich -> Zürich, Switzerland (47.36667, 8.55)
Geneva -> Geneva, Switzerland (46.20222, 6.14569)
Basel -> Basel, Switzerland (47.55839, 7.57327)
```

Each name here has been tied to one specific entry in GeoNames, so besides the name and coordinates printed above you also have a stable identifier for the place, what kind of place it is, the administrative units it belongs to, and a geometry you can map, measure, or export.

## Documentation

Full documentation, including setup, guides, and the API reference, is available at **[docs.geoparser.app](https://docs.geoparser.app)**.

## Project Status

The library is under active development and its architecture is still evolving; while the version remains below `1.0`, minor releases may make breaking changes. [ROADMAP.md](ROADMAP.md) describes the larger changes we intend to make.

## Contributing

Questions, bug reports, and ideas are always welcome via [issues](https://github.com/dguzh/geoparser/issues). Pull requests are appreciated too — see [CONTRIBUTING.md](CONTRIBUTING.md) for local setup and development guidelines.

## Acknowledgments

The Irchel Geoparser originated as part of Diego Gomes' Master's thesis and was further developed with support from the [Department of Geography](https://www.geo.uzh.ch/) at the University of Zurich and the [Public Data Lab](https://publicdatalab.ch/) of the Digitalization Initiative of the Zurich Higher Education Institutions. We thank Prof. Dr. Ross Purves for the opportunity to continue this work as part of a research project.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Geoparser depends on a number of third-party libraries, listed in [pyproject.toml](pyproject.toml). Each is distributed separately under its own license, which pip installs alongside it.

