Carte

Carte is a flexible, extensible reverse-geocode library implemented in Python.

Installation

From PyPI via pip

Carte is available from PyPI via pip.

pip install carte

From source using poetry

Note: It is recommended to build carte in a virtual environment due to dependency version requirements.

From the root of the repository, install the necessary dependencies via poetry:

poetry install

Then, build the wheel:

poetry build

Finally, outside of your virtual environment, install the wheel using pip:

pip install dist/carte-<version>-py3-none-any.whl

Usage

Carte is built using resources which inherit from the Resource class. A Carte instance is instantiated with a list of the Resource types it will query:

import carte

carte_instance = carte.Carte([my_resource_type])

results = carte_instance.query(List of coordinates as tuples...)

Multiple Carte instances may be created, and resources will be shared between them by a backing ResourceStore.

Custom Resources

The flexibility of Carte lies in the Resource class, which queries are passed to sequentially via the query method. The results of each resource query are aggregated and passed to the next, allowing the creation of resources that mutate previous resources' results, such as translating a country's ISO 3166-1 identifier code into a full name.

For examples of Resource classes, see the resources submodule.

Defining your own Resource is as simple as inheriting from the Resource superclass, and implementing the load and query methods.

from carte.resources import resource

class MyCustomResource(resource.Resource):
    def load(self):
        # do stuff...

    def query(self, coordinates, results) -> dict:
        # do other stuff...
        return results

Testing

To run tests, execute the following from the root of the project:

poetry run pytest tests/

License

Carte is licensed under the GNU Lesser General Public License.

Attribution

Carte is inspired by reverse-geocode.