Installation

This guide provides step-by-step instructions to install and set up the Irchel Geoparser on your system.

Installing the Library

Install the Irchel Geoparser using pip:

pip install geoparser

Note

The library uses PyTorch through the sentence-transformers package. If you have a CUDA-enabled GPU, you can significantly speed up geoparsing tasks by installing PyTorch with CUDA support. Visit the PyTorch Get Started page and follow the instructions appropriate for your system.

Installing Gazetteers

The library requires gazetteer data to resolve toponyms to geographic locations. Gazetteers are stored in a SQLite database in your system’s application data directory. You can install gazetteers using a single command that downloads the source data and sets up the database automatically.

Note

The gazetteer CLI command was renamed from download to install.

If you want to try geoparsing quickly, start with GeoNames Cities, a lightweight subset that installs in a few minutes. For real geoparsing work, use the full GeoNames gazetteer instead: it covers far more than cities alone, including towns, natural features, landmarks, and fine-grained place names that the cities subset omits entirely.

GeoNames Cities is a lightweight GeoNames subset intended for getting started quickly. It includes cities with a population of at least 500. Countries and first- and second-level administrative divisions are also included so that names like “France” or “Bavaria” can be resolved, but those features have no geographic data—no coordinates, geometry, or other spatial attributes.

  • Website: geonames.org

  • Coverage: Global cities (population ≥ 500)

  • Required Disk Space: Approximately 700 MB

  • Installation Command:

python -m geoparser install geonames-cities

Installation typically completes within a few minutes. Many place types (towns, rivers, mountains, and so on) are not included at all. Use this gazetteer to experiment with the library; switch to full GeoNames for serious geoparsing.

Database Location

All gazetteer data and project information is stored in a centralized SQLite database located in your system’s user data directory:

  • Windows: C:\Users\<Username>\AppData\Local\geoparser\geoparser.db

  • macOS: ~/Library/Application Support/geoparser/geoparser.db

  • Linux: ~/.local/share/geoparser/geoparser.db

You can remove all data by deleting this database file. Note that this will remove all gazetteers and any projects you have created.

Next Steps

Now that you have installed the Irchel Geoparser, proceed to the Quickstart guide to learn how to use the library.