Skip to main content

Carte is a flexible, extensible reverse-geocode library.

Project description


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


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


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


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

poetry run pytest tests/


Carte is licensed under the GNU Lesser General Public License.


Carte is inspired by reverse-geocode.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

carte-0.2.2.tar.gz (21.5 kB view hashes)

Uploaded source

Built Distribution

carte-0.2.2-py3-none-any.whl (23.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page