molly.apps.places – Places

A database of places with locations


  • providers: A list of providers of entities and information about entities
  • nearby_entity_types: A list of tuples of the form (heading, [entity_types...]), where the entity_types are a list of entity type slugs to be included in this category. Used for deciding which category is shown on the Nearby page
  • associations: A list of tuples which allow entities to be associated with one another, in the form ( ( scheme1, value1, ( heading, ( ( scheme2, value2 ) , ( scheme3, value 3 ) ) ) ), which would associate the entities identified by scheme2:value2 and scheme3:value3 with scheme1:value1 (currently this means that real time departure information for bus stops are additionally shown on the page)


Application('molly.apps.places', 'places', 'Places',
    providers = [
            codepoint_path = CACHE_DIR + '/',
            import_areas = ('OX',),
                 lat_north=52.1, lat_south=51.5,
                 lon_west=-1.6, lon_east=-1.0
            urls = ('',),
            token = 'MyNationalRailToken'
    nearby_entity_types = (
        ('Transport', (
            'bicycle-parking', 'bus-stop', 'car-park', 'park-and-ride',
            'taxi-rank', 'train-station')),
        ('Amenities', (
            'atm', 'bank', 'bench', 'medical', 'post-box', 'post-office',
            'public-library', 'recycling', 'bar', 'food', 'pub')),
        ('Leisure', (
            'cinema', 'theatre', 'museum', 'park', 'swimming-pool',
            'sports-centre', 'punt-hire')),
    associations = (
        ('atco', '9100OXFD', ( # Railway station
            ('Station Forecourt',
                ('atco', '340000006R1'),
                ('atco', '340000006R2'),
                ('atco', '340000006R3'),
                ('atco', '340000006R4'),
                ('atco', '340000006R5'),
                ('atco', '340000006R6'),



ACIS Live provides real time bus information in various UK counties. When enabled, this adds real time bus information to those counties (note, it’s probably a good idea to check with your local council before enabling this!). This has no options.

The areas supported by this provider are:

  • Bristol
  • Buckinghamshire
  • Cambridgeshire
  • Gloucestershire
  • Kent
  • Lancashire
  • York/North Yorkshire
  • Oxfordshire
  • South Yorkshire
  • Wessex
  • West Yorkshire
  • Cardiff


This provider scrapes an ACIS Live instance to try and get route data for the real-time routes ACIS Live knows about. It is heavily recommended you consult with your council before enabling this, as it makes a lot of requests!

This has one option:

  • urls (optional, defaults to all instances): the base URLs of the ACIS Live instances to be scraped for route data



This only implements ATCO-CIF as far as TfGM data is concerned. There are no other public releases of ATCO-CIF data to test against.

This imports ATCO-CIF (public transport timetable and route) data. This allows for bus routes to be rendered, as well as scheduled departure times from a bus stop.

This has one optional option:

  • url: A .zip file containing the .CIF files to be imported



The BBC appear to have deactivated their TPEG feeds, so this importer may not give useful information

This imports TPEG (travel alert) data from the BBC. This has one optional option:

  • url (optional, defaults to UK wide feed): the TPEG feed to import (the BBC provide individual ones for individual counties)


This gives rail stations live departure (and arrival) boards. This has one required and 2 optional options:

  • token: Your National Rail Enquiries token
  • max_services (optional, defaults to 15): The maximum number of services to fetch
  • max_results (optional, defaults to 1): How many boards to fetch at once


This provider scrapes a CloudAmber instance to try and get route data for the real-time routes CloudAmber knows about. It is heavily recommended you consult with your council before enabling this, as it makes a lot of requests!

This has one mandatory option:

  • url: the base URL of the CloudAmber instance to be scraped for route data


This imports entities from the NaPTAN (bus stops, etc) database. This has the following option:

  • areas (optional): a list of ATCO area codes which to import the data from


This imports points of interest from the OpenStreetMap database. It has the following options, all of which are optional:

  • lat_north: A northern bound on latitude which data is imported for (if not set imports all)
  • lat_south: A southern bound on latitude which data is imported for (if not set imports all)
  • lon_west: A western bound on longitude which data is imported for (if not set imports all)
  • lon_east: An eastern bound on longitude which data is imported for (if not set imports all)
  • url: The URL to the OpenStreetMap dataset to be imported (defaults to the England dataset)
  • entity_type_data_file: A YAML file (see below) which contains the entity type definitions for the OSM importer
  • osm_tags_data_file: A YAML file (see below) which contains the OSM tags to be imported, and how they map to Molly’s entity types (defined in entity_type_data_file)
  • identities_file: A YAML file (see below) which contains a mapping between any OpenStreetMap nodes or ways and an external data source which defines when the OSM entity is identical to the entity in the external data source.

Entity Type data files

This file defines a dictionary in YAML entity-type definitions for Molly, where the key is the slug of the entity type to be created. Any entity type which you want an OSM type to be matched to should exist in this file.

Each definition defines the name of the entity type, the singular and plural forms of it, the name of the category it belongs to, and defaults for whether or not they are shown in the nearby and category lists (these can be overriden by the database, and these settings are only respected on first import). Also included are a list of parent types (e.g., “ice cream cafe” objects also belong to the “food” type, so “food” is a parent of “ice cream cafe”).

This file is optional, and Molly ships with a sensible set of defaults (see molly/apps/places/providers/data/osm-entity-types.yaml).


Note for translators! This file isn’t in Python, so isn’t marked up! You will, however, still want the names in here to be translated, so you need to make sure your .po files include things defined here.


  category: Amenities
  parent-types: []
  show_in_category_list: true
  show_in_nearby_list: true
  verbose_name: bank
  verbose_name_plural: banks
  verbose_name_singular: a bank
  category: Amenities
  parent-types: [place-of-worship]
  show_in_category_list: false
  show_in_nearby_list: false
  verbose_name: church
  verbose_name_plural: churches
  verbose_name_singular: a church

The example above defines two entity types for the OSM importer to deal with. The OSM tag data file can then refer to the slugs (the keys: e.g., ‘bank’ and ‘church’) when mapping OSM tags to Molly entity types.

OSM tag data files

This file defines which OSM tags are to be imported, and also which entity types in Molly they map on to. Each entity in the list contains at least two keys: ‘entity-type’ and ‘osm-tag’. This means OSM items which have a tag which matches osm-tag will be imported, and assigned to entity-type.

In this file, you can also define subtags, which allow for specialisations of OSM tags and Molly types. For example, you may have an OSM item of type ‘place_of_worship’, but in Molly represent different faiths as different types. In this case, you can look at the religion tag, to determine a more specialised entity type to tag with. Another way to think about this is as an AND clause for the OSM tags. e.g.,

- entity-type: place-of-worship
  osm-tag: amenity=place_of_worship
  - {entity-type: chapel, osm-tag: place_of_worship=chapel}

In this case, OSM entities which have tags ‘amenity=place_of_worship’ AND ‘place_of_worship=chapel’ will be imported with the entity type of ‘chapel’, and entities which only have a tag ‘amenity=place_of_worship’ will be imported with the entity type ‘place-of-worship’.


All entity types referred to here must be defined in the corresponding OSM entity type data file.


- {entity-type: museum, osm-tag: amenity=museum}
- entity-type: car-park
  osm-tag: amenity=parking
  - {entity-type: park-and-ride, osm-tag: park_ride=bus}

In the example above, this imports OSM items with a tag ‘amenity=museum’ as the Molly entity type ‘museum’, OSM items with a tag ‘amenity=parking’ as entity type ‘car-park’, and OSM items with the tags ‘amenity=parking’ AND ‘park_ride=bus’ as entity type ‘park-and-ride’.

Identity files

The file defines which OpenStreetMap nodes or ways are identical to an entity already in your database, which has been imported from another source. When such a node or way is encountered (and would be imported because it contains a tag in the entity type data file), then the OSM metadata is then added to the other entity, rather than a new entity being created.

W23679234: oxpoints:23232416
W23679567: oxpoints:23232405

In the example above, the OpenStreetMap way with ID 23679234 (which would normally get imported with URL is instead mapped on to the entity at, i.e., /places/osm:W23679234/ is identical to /places/oxpoints:23232416/.


This imports postcodes from the Code-Point Open database. It has the following options:

  • codepoint_path: A path to where the Code-Point Open zip file is get on disk. If the file does not exist, it is obtained from
  • import_areas (optional): If set, it is a list of postcode prefixes which limits the area which is imported (this is highly recommended due to the size of the postcode database!)

Writing Your Own Providers