Skip to main content

PyCartociudad contains Python functions to access the CartoCiudad REST and WPS API (REST y WPS) from IGN with spanish cartography services.

Project description

pycartociudad Documentation Status

pycartociudad contains Python functions to access the CartoCiudad REST and WPS API (REST y WPS) from IGN with spanish cartography services.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.


To use the pycartociudad package you will need to have python installed (at least version 3.8). For detailed instructions, please check the Downloading Python guide

Dependencies can be managed through a pipenv wrapper. In order to install pipenv, check the pipenv installation documentation.


To install the latest published PyPI version of pycartociudad:

pip install pycartociudad

To upgrade an already installed pycartociudad package from PyPI:

pip install --upgrade pycartociudad

The pycartociudad development repository can be found in the pycartociudad GitHub repository. To make a local copy of the pycartociudad repository, clone it or download is as a zip file.

To get a development env running, go to the downloaded or cloned pycartociudad folder and install it using pipenv:

$ pipenv install

Running the tests

To run a subset of tests:

$ python -m unittest tests.test_geocode
$ python -m unittest tests.test_reverse_geocode



Built with

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.


The pycartociudad documentation can be found in pycartociudad readthedocs.

Details on the API implementation can be found in the official Cartociudad API specs.


Please read CONTRIBUTING.rst for the process of submitting pull requests to us.

For details on our code of conduct, check the PyLadies Code of Conduct.



Geocoding is the geolocation of addresses in Spain via Cartociudad API calls. Calling the geocode function returns the details of the closest address in Spain to the indicated address.

>>> import pycartociudad as pycc
>>> pycc.geocode('Plaza mayor 1, madrid')
{'id': '280790001063', 'province': 'Madrid', 'comunidadAutonoma': 'Comunidad de Madrid', 'muni': 'Madrid', 'type': 'portal', 'address': 'MAYOR', 'postalCode': '28012', 'poblacion': 'Madrid', 'geom': 'POINT (-3.7066353973101624 40.41505683353346)', 'tip_via': 'PLAZA', 'lat': 40.41505683353346, 'lng': -3.7066353973101624, 'portalNumber': 1, 'stateMsg': 'Resultado exacto de la búsqueda', 'state': 1, 'countryCode': '011', 'refCatastral': None}

Reverse geocoding

Reverse geocoding is the search of an address details based on latitude and longitude coordinates.

>>> import pycartociudad as pycc
>>> pycc.reverse_geocode(40.4472476241486,-3.7076498426208833)
{'id': '280790165933', 'province': 'Madrid', 'comunidadAutonoma': 'Comunidad de Madrid', 'muni': 'Madrid', 'type': None, 'address': 'REINA VICTORIA', 'postalCode': '28003', 'poblacion': 'Madrid', 'geom': 'POINT (-3.707649842620833 40.447247624136764)', 'tip_via': 'AVENIDA', 'lat': 40.447247624136764, 'lng': -3.707649842620833, 'portalNumber': 22, 'stateMsg': 'Resultado exacto de la búsqueda', 'state': 1, 'priority': 0, 'countryCode': '011', 'refCatastral': None}

Reverse geocoding can be performed to look for cadastral details with the cadastral parameter

>>> pycc.reverse_geocode(40.4472476241486,-3.7076498426208833, cadastral=True)
{'id': None, 'province': None, 'comunidadAutonoma': None, 'muni': None, 'type': None, 'address': '0079609VK4707G', 'postalCode': None, 'poblacion': None, 'geom': 'POINT (-3.7076498426208833 40.4472476241486)', 'tip_via': None, 'lat': 40.4472476241486, 'lng': -3.7076498426208833, 'portalNumber': 0, 'stateMsg': 'Resultado exacto de la búsqueda', 'state': 1, 'priority': 0, 'countryCode': '011', 'refCatastral': 'AV REINA VICTORIA 22 MADRID (MADRID)'}

Get location info

The get_location_info function gets extra information of a location using official spanish web map services, such as cadastre, census or geocoding information.

>>> import pycartociudad as pycc
>>> pycc.get_location_info(40.4472476241486,-3.7076498426208833)
{'cadastral_ref': '0079609VK4707G', 'census_section': '2807906001', 'district_code': '2807906', 'id': '280790165933', 'province': 'Madrid', 'comunidadAutonoma': 'Comunidad de Madrid', 'muni': 'Madrid', 'type': None, 'address': 'REINA VICTORIA', 'postalCode': '28003', 'poblacion': 'Madrid', 'geom': 'POINT (-3.707649842620833 40.447247624136764)', 'tip_via': 'AVENIDA', 'lat': 40.447247624136764, 'lng': -3.707649842620833, 'portalNumber': 22, 'stateMsg': 'Resultado exacto de la búsqueda', 'state': 1, 'priority': 0, 'countryCode': '011', 'refCatastral': None}

Route between two points

This function gets the route between two points (encoded with their latitude-longitude coordinates), either walking or in a vehicle.

>>> import pycartociudad as pycc
>>> d = pycc.route_between_two_points(40.447313139920475,-3.704361232340851,40.44204376380937,-3.699671450323607)
>>> for i in d['instructionsData']['instruction']:
...     print(i['description'])
Gire justo a la derecha por CALLE SANTA ENGRACIA
Gire a la izquierda por CALLE RIOS ROSAS
Objetivo logrado


For a list of contributors, check the PyLadies pycartociudad contributor list


  • Free software: CC-BY 4.0

The data returned by this package is provided by IGN web services and implies the user’s acceptance of a CC-BY 4.0 license. More info available in the IGN license specs.


0.1.0 (2020-12-15)

  • First release on PyPI.

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

pycartociudad-0.1.0.tar.gz (104.8 kB view hashes)

Uploaded Source

Built Distribution

pycartociudad-0.1.0-py2.py3-none-any.whl (14.7 kB view hashes)

Uploaded Python 2 Python 3

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