Working efficiently with Spanish geographical entities

We are big fans of the Open Source community since we learned to program. Everyday we use many libraries created by people like us in their spare time. Apart from the time we save in writting code, what’s also very valuable in using open source is the knowledge implicit in the code: open source is not just sharing code for free, but a solution to a given problem in the form of code, patterns and documentation.

We want to give back to the community with a small project we use in many of our projects, it’s called ine-places. We are releasing it as a Ruby gem, but in the README you can find a bit of our experience working with Spanish regions, where the data can be found, in which format, and so on.

The Problem

We are not dealing with a big problem, in fact it’s quite simple. We needed a way to programmatically access to the official list of municipalities, autonomous regions and provinces from Spain with an unique ID shared accross all the official institutions and an official name. Thankfully that classification exists in the National Institute of Statistics (the acronym is INE in Spanish).

The unique IDs will allow us to identify the entity in any dataset generated by an official institution. The official names are necessary to be included in lists, search forms, or pages.

Our solution

We created a package with the list of autonomous regions, provinces and municipalities in a Ruby gem. We also included Ruby well tested classes and modules to work with, in a very clean way:

We don’t want to go deeper in the details, but the list of entities is efficiently memoized when accessed, and the library provides a suitable method to pre-load all the data: INE::Places.preload. It allows to create tools such a suggestion form, with super-fast response times.

Also, this week we have released a new and experimental feature we call hydratation. Given a dataset which contains (apart from the data values) a column referring to the IDs, it’s possible to hydratate the Ruby classes with those values:

This is a very neat way to extend the models using external datasets of information. After solving this problem in different projects using different approaches this is, by the moment, our favourite.

Plans

We have some plans for this gem:

• allow the hydratation from an API endpoint, that could be the INE itself, a private data source, or CartoDB
• make the gem more generic, maybe supporting geographical entities from the EuroStat
• we are considering a Javascript version to enable all this toolkit to be available in the client side

Help

Want to help testing the gem or adding some of the features above? Please write to us or feel free to fork the project and send us a pull request. We are open to suggestions and new ideas.

And, if you are using the gem and it’s been helpful just drop us a line or invite us to a beer.