Data Mapping

The data mapping defines which OSM feature types should be imported in which table. The mapping is described with a Python file using classes from imposm.mapping package.

See defaultmapping.py as an example.

Tables

There are three classes for the base geometries: Points, LineStrings and Polygons. All three classes take the same arguments:

name

The name of the resulting table (without any prefix).

mapping

The mapping of tags keys and tag values that should be inserted into this table.

fields

Mapping of additional tags into table columns.

field_filter

Filter table entries based on field values.

with_type_field

Controls if the the value of the mapped key/value should be stored in the type column. Defaults to True.

mapping

Mapping should be a dictionary where the keys are the feature keys (e.g. highway, leisure, amenity, etc.) and the values are tuples of the feature values (e.g. motorway, trunk, primary, etc.).

For a table with bus stops, tram stops and railways stations and halts the mapping should look like the following:

mapping = {
    'highway': (
        'bus_stop',
    ),
    'railway': (
        'station',
        'halt',
        'tram_stop',
    )
}

fields

Fields should be a list (or tuple) of column name and column type tuples. You can use fields to add additional columns to your tables. There are predefined classes for the most common types. These classes can do processing on the values, like converting 1, yes and true to TRUE for boolean columns.

For example:

fields = (
    ('tunnel', Bool()),
    ('bridge', Bool()),
    ('oneway', Direction()),
    ('ref', String()),
    ('z_order', WayZOrder()),
)

Most types will use the column name to get the value from the tags. For example, ('tunnel', Bool()) will convert the values of the key tunnel to a boolean.

Name field

There is a default field for names if you do not supply a field for the name column. You can change the default with set_default_name_type().

imposm.mapping.set_default_name_type(type, column_name='name')

Set new default type for ‘name’ field.

set_default_name_type(LocalizedName(['name:en', 'int_name', 'name']))

Classes

class imposm.mapping.Points(name, mapping, fields=None, field_filter=None, with_type_field=None)

Table class for point features.

PostGIS datatype:  POINT

class imposm.mapping.LineStrings(name, mapping, fields=None, field_filter=None, with_type_field=None)

Table class for line string features.

PostGIS datatype:  LINESTRING

class imposm.mapping.Polygons(name, mapping, fields=None, field_filter=None, with_type_field=None)

Table class for polygon features.

PostGIS datatype:  GEOMETRY (POLYGON does not support multi-polygons)

Example Mapping

Here is a example of a data mapping that creates a table towers. All nodes with man_made=tower or man_made=water_tower will be inserted. It will also create the column height with the values of the height tag as integers. [1]

 towers = Points(
   name = 'towers',
   mapping = {
     'man_made': (
       'tower',
       'water_tower',
     )
   }
   fields = (
     ('height', Integer()),
   )
)

[1]	It will set the height to NULL for non-integer values (like values with a unit, 15 m or 80 ft). A custom column type Height() could automatically convert these values to a common unit. This is left as an exercise for the reader.

Column types

class imposm.mapping.String

Field for string values.

PostgreSQL datatype:  VARCHAR(255)

class imposm.mapping.Bool(default=True)

Field for boolean values. Converts false, no, 0 to False and true, yes, 1 to True.

PostgreSQL datatype:  SMALLINT

class imposm.mapping.Integer

Field type for integer values. Converts values to integers, defaults to NULL.

PostgreSQL datatype:  INTEGER

class imposm.mapping.Direction

Field type for one-way directions. Converts yes, true and 1 to 1 for one ways in the direction of the way, -1 to -1 for one ways against the direction of the way and 0 for all other values.

PostgreSQL datatype:  SMALLINT

class imposm.mapping.OneOfInt(values)

Field type for integer values. Converts values to integers, drops element if is not included in values.

PostgreSQL datatype:  SMALLINT

class imposm.mapping.ZOrder(types)

Field type for z-ordering based on the feature type.

Parameters:types – list of mapped feature types, from highest to lowest ranking PostgreSQL datatype:  SMALLINT

class imposm.mapping.WayZOrder

Field type for z-ordered based on highway types.

Ordering based on the osm2pgsql z-ordering: From roads = 3 to motorways = 9, railway = 7 and unknown = 0. Ordering changes with tunnels by -10, bridges by +10 and layer by 10 * layer.

PostgreSQL datatype:  SMALLINT

class imposm.mapping.PseudoArea

Field for the (pseudo) area of a polygon in square meters.

The value is just an approximation since the geometries are in EPSG:4326 and not in a equal-area projection. The approximation is good for smaller polygons (<1%) and should be precise enough to compare geometries for rendering order (larger below smaller).

The area of the geometry is multiplied by the cosine of the mid-latitude to compensate the reduced size towards the poles.

PostgreSQL datatype:  REAL

New in version 2.3.0.

class imposm.mapping.Name

Field for name values.

Filters out common FixMe values.

PostgreSQL datatype:  VARCHAR(255)

New in version 2.3.0.

class imposm.mapping.LocalizedName(coalesce=['name', 'int_name'])

Field for localized name values. Checks different name keys and uses the first key with a valid value.

Parameters:coalesce – list of name keys to check PostgreSQL datatype:  VARCHAR(255)

New in version 2.3.0.

class imposm.mapping.Type

Field for type values (i.e. the value of the mapped key/value).

Use this in combination with with_type_field=False of the mapping class, if you want to store the value of the mapped key/value in a different column.

For example, to get a column road_class instead of type:

roads = LineStrings(
    with_type_field = False,
    name = 'roads',
    mapping = {
        'highway': (
            'motorway',
            'trunk',
            'secondary',
        ),
    },
    fields = (
        ('road_class', Type(),),
    ),
)

PostgreSQL datatype:  VARCHAR(255)

New in version 2.4.0.

class imposm.mapping.Class

Field for class values (i.e. the key of the mapped key/value).

Use this if you want to store the key that was used for this mapping. For example, the following mapping will create a column class that will have the value landuse or natural, depending on the feature.

landusages = Polygons(
    name = 'landusages',
    fields = (
        ('class', Class()),
    ),
    mapping = {
        'landuse': (
            'wood',
        ),
        'natural': (
            'wood',
        ),
    }
)

PostgreSQL datatype:  VARCHAR(255)

New in version 2.4.0.