bbd - bbbike data format description


Sorry - parts of this documentation are still in German...

bbd is a simple format for describing points and polylines for geographic information systems.

Bbd files consist of newline-terminated records in the format:

    Name TAB Category SPACE x,y SPACE x,y ...

Coordinate lines (data lines)

A descriptive name, for example the street name, or (for attribute layers) a description of the attribute category. This field must not contain any TAB characters.

If there is a main name and a descriptive part, then the latter should be separated by a | character. This helps for intelligent labelling, i.e. leaving out unimportant parts if necessary. Example: Ringenwalde|(Uckermark) could be labelled as Ringenwalde or Ringenwalde (Uckermark).

The category of this point or polyline. If the category matches #rrggbb (where rr, gg and bb are hexadecimal values), then this denotes a color for the representation in the Perl/Tk interface. A prefix of F: denotes that the polyline should be treated as a polygon and filled with a solid color. Note that the polygon is always closed, but it is optional to make the first and last the same.

If the category matches forwardcat;backwardcat, then forwardcat applies to the street in forward direction and backwardcat applies to the street in backward direction. Either forwardcat or backwardcat may be empty; in this case the category applies only to the other direction.

The X category should be used if there is no category.

Other predefined categories are listed below. The category should not contain any spaces.

   DRAFT (not yet in use!): Change the category format to:

       <cat> = <onewaycat> ; <onewaycat> |

       <onewaycat> = F=? <basiccat> (: <attrkey> (= <attrval>)?)*

       <basiccat>  = [^:;]+
       <attrkey>   = [^:;=]+
       <attrval>   = [^:;=]+

   Changes for data files:
     F:cat becomes F=cat
     ?::inwork becomes ?:inwork
     F:SW|IMG:church.gif|ANCHOR:s becomes F=SW:IMG=church.gif:ANCHOR=s
   Maybe (no, too much typing):
     #rrggbb becomes X:COLOR=#rrggbb

   cat is now really attr. Reflect in description, maybe also in
   variable names.
A coordinate. x and y should be integer or float values. The datum and grid of the coordinates should be handled by the software. It is recommended that x and y should denote the easting and northing in meters (as in GKK or UTM). A record may contain an unlimited number of coordinates, though there may be limitations in the interpreting software. See also below for the map directive in Directive lines.

Directive lines

If a line begines with a hash sign followed by a color (#:), then the line is treated as a directive. There are global directives, line directives and block directives. Global directives should be specified at top of the file before the first data line and should be separated by the data lines with an empty directive line. For example:

 #: encoding: utf-8
 #: map: polar
 ... data lines

Line directives are valid for the next line only:

 #: add_fragezeichen: Is this really correct?
 Main street: bad cobblestone	Q3 13.5,52.5 13.4,52.5

Block directives are valid for the specified block. Block directives are markes as such:

 #: directive_name directive_arguments ... vvv
 ... data lines
 #: directive_name ^^^

The v and ^ markers can be repeated an indefinite number of times, but at least three times.

Directives have always at least the directive name (the first word token in the line) and zero, one or more directive values:

 #: directive_name
 #: directive_name: val1
 #: directive_name: val1 val2

The colon (:) after the directive name is optional. The following is equivalent:

 #: encoding utf-8
 #: encoding: utf-8

Global directives

type: bbd_type
This global directive sets the type of the bbd file. If given then it should be put into the first line to serve as a kind of "magic". A possible type would be bbr or bbbike route, once I get rid of the .bbr format.
map: maptype
This global directive sets the coordinate system of the bbd file. If no map directive is specified, then the proprietary bbbike coordinate system is used. For WGS84 coordinates specified as DDD use the maptype polar.
title: title string
This global directive sets the title or some descriptive text for the file.
version: RCS or CVS identifier string
This global directive introduces an RCS/CVS Id string. Not recommended if a modern version controlling system like git is used.
encoding: encoding name
Treat this file as encoded in the given encoding (all names accepted by Perl's Encode may be used, see Encode::Supported). If not set, then iso-8859-1 is assumed.

The degree of support for encodings in bbbike.cgi and the Perl/Tk implementation differs. iso-8859-1 is supported best. utf-8 is considered to work in most, if not all places of the code. Other encodings are at least known to NOT work with the XS implementation for the fast street and point plotting. The pure perl implementation is fine.

listing_sort: sort_method
Define a sorting method for street/point listings. Normally listings will be sorted alphabetically (sort method alphabetic). If the listing should appear as in the bbd file, specify unsorted. natural should be used for "natural" sorting (see Sort::Naturally).

Plotting hint directives

Plotting hint directives are used to control plotting of items. The directives can only be set as global directives. The directives explained below exist in two forms:

directive: ...
The directive is valid for all items (unless overriden by per-category directives).
directive.category: ...
The directive is valid for items with the named category (this overrides directives without category specification).

The list of plotting hint directives:

line_color: color
line_color.category: color
Define the color for line items. color should be in the form #rrggbb.


 #: line_color: #808080
 #: #ff8080

Compatibility: category_color.category is still recognized as an alternative to line_color.category. Maybe this will removed some day.

XXX: Maybe use item_color instead of line_color, because colors apply also to points and areas!

XXX: Hmmm, it seems that str_color is (also?) in use, see tmp/streets-accurate.bbd

line_width: width
line_width.category: width
Define the width of line items. The width should either be one value, or six comma-separated values. If it's only one value, then it is taken as the width at approx. 1:17000, and other widths are calculated proportionally to $line_width{default}. If it's six values, then this should represent the widths for the six standard scales defined by bbbike.
line_length: length
line_length.category: length
Define the length of line items. In the Perl/Tk interface this is currently used for oneway and blocked symbols.

XXX: The form with category is NYI!

XXX: Maybe this should make it possible to define lengths for specific zoom levels, like in the bbbike standard definitions.

line_dash: x, y, ...
line_dash.category: x, y, ...
Define the default dash pattern for line items. See DASH PATTERNS in Tk::Canvas for the list integer syntax.


 #: line_dash: 1,1
 #: line_dash: 2,4

Compatibility: category_dash.category was formerly used instead of line_dash.category and is still recognized, but will be removed some day.

line_capstyle: capstyle
line_capstyle.category: capstyle
Define the capstyle for line items. Valid values are butt, projecting, or round (see Tk::Canvas).

XXX: Currently category_capstyle.category is used instead of line_capstyle.category.

line_arrow: arrowspec
line_arrow.category: arrowspec
Define whether arrows should be drawn on line items. Valid values are none, last, first, or both (see Tk::Canvas).


 #: line_arrow: last
 #: both
line_shorten: boolean
line_shorten.category: boolean
Define whether line items should be shortened on both ends.

XXX: Currently category_line_shorten.category is used instead of line_shorten.category.

line_shorten_end: boolean
line_shorten_end.category: boolean
Define whether line items should be shortened at the end.

XXX: Currently category_line_shorten_end.category is used instead of line_shorten_end.category.

line_directed_weight: boolean
line_directed_weight.category: boolean
Define whether lines are directed and present weights.
line_do_offset: boolean
line_do_offset.category: boolean
Define whether lines should be plotted with an offset or not. By default, lines which have a "splitted" category for the forward and backward directory (e.g. A;B) are plotted with an offset, but this can be disabled by explicitely setting line_do_offset to a false value.
item_size: integer
item_size.category: integer
Define the size of items (for example base label font size or the size of point items in pixels).

XXX: The category-less form is NYI! XXX: Currently category_size.category is used instead item_size.category.

item_image: image_name
item_image.category: image_name
Define an image for point items. The image name is usually without suffix and will be searched in the default bbbike image directories, if specified relative.

XXX: The category-less form is NYI! XXX: Currently category_image.category is used instead item_image.category.

item_stipple: image_name
item_stipple.category: image_name
Define a stipple (which is usually an xbm image) for area items.

XXX: The category-less form is NYI! XXX: Currently category_stipple.category is used instead item_stipple.category.

layer_stack: how:tag
Define how the data should appear in the layer stacking order. how is either above or below and tag is another layering tag used in bbbike (some examples are s for the street layer or w for the water layer --- consult the bbbike source, variable @normal_stack_order for more tags).

XXX This is experimental and likely to change!

Line/block directives

by: source
according_to: source
Denotes that the information in the next block or line was provided by source. This may be an email address or full name of an author, an URL providing more information, a Message-Id of a mail or posting, a date, or a combination of all. according_to: is an alias for by:.
corrected_by: source previous -> current
Used after a by directive for a correction. It is advisable to put the previous a small note of the previous and maybe also the current entry after the source.
confirmed_by: source
Denotes that the information in the next block or line was confirmed by source.
valid: YYYYMMDD-
valid: -YYYYMMDD
Define the validity period of records. Other tools (e.g. grepstrassen) may remove non-valid records automatically.

If the value is preceded by a !, then the validation period is inverted.

Note: in future Strassen::Core may deal automatically (or optional) with removal of non-valid records.

NOTE: Makefile rules don't cope well with the ability that source files are processed differently depending on time.

The next block or line is just a temporary feature. Typically this directive is accompanied by a next_check directive to specify the end date, so systems like "fragezeichen-nextcheck" can include this feature in their lists.

Earlier versions of this document suggested to put the date information into the Name field of the data line, preferred in a ISO-date similar notation (e.g. YYYY-MM-DD - YYYY-MM-DD for a starting and an end date). This may still be done additionally to the next_check directive, but is not evaluated by automatic scripts.

XXX: why
The next block or line is unsure or unclear information, and usually has to be researched on-site. The why text specifies an additional comment. This note should not appear in the processed data.

Earlier versions also defined unsure as an alias for XXX (or even the other way around), but in reality unsure was almost never used and also never considered in supporting scripts, so its use is now deprecated.

XXX_checklater: why
Like XXX, and additionally attach the "checklater" attribute.

NOTE: Currently it's not recommended to use this tag. It is better to use just XXX in conjunction with next_check or last_checked, because the current infrastructure (supporting scripts etc.) have better support for this.

XXX_prog: why
The next block or line contains problematic information due to problems in the using programs, i.e. bbbike and bbbike.cgi.

For example this can be used if stacking information has to be given using ordering in the data file, but bbbike should really have a layer_stack attribute.

In the past it was also used for the cyclepath layer, because of suboptimal rendering in points with large angles (more than 45° or so). Here the layer item has to be broken into two items to fix the rendering problem. But this is solved in bbbike since July 2009.

XXX_indoor: why
The unclear information can only be researched "indoor", and usually not on-site.
XXX_outdoor: why
Deprecated. Usually this is the same as XXX, and scripts don't support this type anymore.
XXX_osm: why
An issue in OpenStreetMap data, e.g. incorrectly spelled street name or wrong ways.
alias: name
Define another known name for the next line.
alias_wide: name
Special alias name to be used for "wide region" routings. In "inner city" routing the real name should be used instead.


    #: alias_wide: Oranienburg - Bernau (B273)
    Bernauer Str. (B273)	B ...,...
name: lang: name
The name in another language, specified by lang in ISO 639 codes.
oldname: when: name
An old name for the next line. when is a time specification (best: some kind of ISO dates, but this is not yet specified). Unknown dates in when should be marked with a question mark. Multiple oldname directives are allowed for one record.


    #: oldname: ?-20001001: Oldname street
    #: oldname: 20001001-2005: Not-so-old-name street
ignore_oldname_file: yes
Ignore this oldname entry when generating the oldnames data file. This is useful if for example only a part of the street was renamed.
section: section name
The next block is part of a named section. Sections may be nested.
The next line/block is ignored for some processing instructions. For example, "busroute_N" entries in comments_misc-orig are skipped when creating comments_misc.
append_comment: comment
Useful for preprocessing bbd data files to add a comment to each record in the block.
attributes: attribute, ...
attrs: attribute, ...
Define additional attributes for the following line or block. The attributes may be used in a preprocessing script to generate additional layers. attrs is an alias for attributes.
note: string
A free text note, which shouldn't (but may) appear in the processed data.
see_also: string
A free text note, which refers to more information. This should be typically a URL.
last_checked: date
last_checked: date (by: name)
Date (and optionally surveyor) of the last check for a feature. This is useful in conjunction with XXX or add_fragezeichen directives, to generate automatic list of streets to be surveyed again.
next_check: date
Recommended date for a next survey for a feature. This could be for instance the intended finish date of road construction.

For generating survey lists, it could also be useful to generate synthetic next_check directives out of last_checked value, e.g. one month after the last check. The default interval could be set by the check_frequency directive.

check_frequency: daysd
Set a check frequency for the synthetic generationg of next_check directives. If not set, then the default could be one month or so.
as_of: date
Last verified at the given date. The date should be in a ISO-8601-like notation, with possible abbreviations: YYYY-MM-DD or YYYY-MM or YYYY.

The difference between last_checked and as_of is subtle; it is expected that last_checked-tagged entries should be actively checked for changes, and as_of-tagged entries only passively.

Currently as_of directives appear in data/comments_ferry-orig for ferry timetable and fare information.

url: string
An (official) URL referring to more information.
add_fragezeichen: string
Some postprocessing code may add the following line with the descriptive text string to the fragezeichen file.
complete: yes|no
May be used to mark a feature as complete or incomplete (e.g. cycle routes).
priority: string
A priority for checks. The priority string should be something between #A (highest) and #C (lowest).
linked: string
May be used for check purposes. Currently only utilized in ortsschilder-orig, where the linked name is to be used to do checks against orte-orig/orte2-orig.

Obsolete and to-be-decided directives

off: when comment
Currently used in ampeln-orig, needs to be decided on the exact format and even on the directive name. Example entry:
    #: off: night (seen 2001-12-25)

The comment part may be completely missing.

Currently the following labels are used in the when part: night, weekend, holiday, week day names, except_schooltime, except_event, HH:MM-HH:MM.

internal_note: string
A free text note, which must not appear in the processed data. It is just a note for editors.

Currently I think the XXX_... is better suited for this task, as it can give more specific information.

unverified_by: source
Same as "by:" for unverified data. "Unverified" means that there's no communication channel back to the information provider. Nowadays this would be a couple of "by:" and "add_fragezeichen:" or "XXX:" directives.

Comment lines

If a line begins with a hash sign (#), then it is treated as a comment. Empty lines are ignored.


Here's a list of special categories:


Used in files: strassen, landstrassen, landstrassen2. Usually strassen is used for city streets, landstrassen for streets in the region around the city, and landstrassen2 for streets in the wider region. But it is also possible to work only with one file strassen.

Freeways (Bundesautobahn)
Important main streets (wichtige Hauptstraßen). Entspricht von der Kfz-Dichte meist Bundesstraßen. In osm this is a highway=primary within cities.
Main streets (Hauptstraßen). In osm this is a highway=secondary.
Experimental, not yet fully supported in bbbike. In osm this is a highway=tertiary.
Nebenstraßen. In osm this is a highway=residential.
Für Kfz gesperrte Straßen. In osm this is either a highway=footway or highway=cycleway.
Places (Plätze).


Used in files: gesperrt, gesperrt_car. gesperrt is usually used for blocked streets relevant for cyclists, while gesperrt_car is for blocked streets for motorized vehicles.


Used in files: radwege_exact.

Kein Radweg.
Normaler nicht benutzungspflichtiger Radweg.
Benutzungspflichtiger Radweg.
Suggestivstreifen für Radfahrer.
Busspur (eventuell nur temporär), auch für Radfahrer frei.
Verkehrsberuhigte Straße.
Benutzungspflichtiger Zweirichtungsradweg, Gegenrichtung.
Nicht benutzungspflichtiger Zweirichtungsradweg, Gegenrichtung.
Hauptstraße mit zusätzlichem Nebenstreifen, aber auch von Kfz nutzbar (Beispiele in Berlin: Heerstr., Unter den Eichen am Botanischen Garten).
Radweg vorhanden, aber nicht weiter kategorisiert.

Folgende Kategorien können in der "-orig"-Variante ein "?" nachgestellt haben, um anzuzeigen, dass Informationen fehlen: RW3, RW4 (Benutzungspflicht unbekannt) und RW5 (Gültigkeitsdauer der Busspur fehlt).


Used in files: ubahn, sbahn, rbahn, ubahnhof, sbahnhof, rbahnhof.

Regionalbahnen außerhalb des Stadtgebiets.
Regionalbahnen Zone A.
Regionalbahnen Zone B.
Regionalbahnen Zone C.
Regionalbahnen außer Betrieb oder ohne regelmäßigen Betrieb.
Regionalbahnen in Bau.
Güterbahnen, Verbindungskurven.
Parkbahnen, Kleinbahnen.
S-Bahnen außerhalb des Stadtgebiets.
S-Bahnen Zone A.
S-Bahnen Zone B.
S-Bahnen Zone C.
S-Bahnen außer Betrieb.
S-Bahnlinien in Bau.
U-Bahnen außerhalb des Stadtgebiets.
U-Bahnen Zone A.
U-Bahnen Zone B.
U-Bahnen Zone C.
U-Bahnen außer Betrieb.
U-Bahnlinien in Bau.


Qualität der Wege (Fahrbahnbeschaffenheit).

Used in files: quality_s, quality_l. quality_s is usually used for city streets, while quality_l is for streets in the region around the city.

Beste Qualität, keine Einschränkungen.
Gute Kopfsteinpflasterstrecken, mäßiger Asphalt, etwa 25 km/h Höchstgeschwindigkeit.
Gewöhnliche Kopfsteinpflasterstrecken, schlechter Asphalt, Waldwege, etwa 18 km/h Höchstgeschwindigkeit.
Schlechte Kopfsteinpflasterstrecken, sandige Strecken, etwa 13 km/h Höchstgeschwindigkeit.

Es ist möglich, eine Tendenz mit einem angehängten - (besser) oder + (schlechter) anzugeben, also beispielsweise Q2+ für eine mäßige Qualität mit Tendenz zur guten Qualität. Diese Tendenzen werden bislang nur bei der Erfassung verwendet, aber (noch) nicht beim Routing oder der Kartendarstellung.

Andere, nicht fahrbahnbezogene Handicaps, zum Beispiel Beeinträchtigungen durch Fußgänger oder enge Kurven. Used in files: handicap_s (used for city streets), handicap_l (used for streets in the region around the city).

Auf 25 km/h.
Auf 18 km/h.
Auf 13 km/h.
Auf Schrittgeschwindigkeit (z.B. in Fußgängerzonen).


Vorfahrt für Straßenbahnen
Kreuzung ohne Vorfahrtsregelung


Used in files: comments_cyclepath (alternative way to attribute cyclepaths), comments_ferry (e.g. time-tables or fares of ferries), comments_kfzverkehr (categorized amount of motorized traffic - Abschätzung des Kfz-Verkehrs), comments_misc (other comments), comments_mount (mounts with grades - Steigungen), comments_path (path instructions), comments_route (numbered cycle routes - ausgeschilderte Fahrradrouten), comments_tram (tramway on street).

Only for records with three points. Comment is valid for point B if driving from A to C.
Only for records with two points. Comment is valid for point A if driving from A to B.
Same as CP;, but valid for both directions.
Same as CP2;, but valid for both directions.
Comment is valid for the whole route in this direction.
Comment is valid for the whole route in both directions.
Path instruction (genauere Wegbeschreibung). (This is in fact a generalisation of CP2; allowing more than two points)
Dieser Weg ist gesperrt (z.B. Abbiegen nicht möglich), aber eine Umfahrung ist möglich ... siehe auch Kategorie 3 in BLOCKINGS.

NB: Diese Kategorie wird bislang noch nicht verwendet und bedarf deswegen einer Überprüfung.

-2 relativ ruhiger Kfz-Verkehr
+2 relativ starker Kfz-Verkehr
Relativ zu der Kategorie einer Straße (von Nebenstraße NN bis zur Bundesstraße B) kann das subjektive Empfinden der Kfz-Dichte mit -2 bis +2 angepasst werden.


Used in files: flaechen. Mostly prefixed with F:, see above.

Cemeteries. May have a religion tag, e.g. F:Cemetery|religion=muslim or F:Cemetery|religion=jewish.
Orchards; especially allotments (Kleingärten).
Sports fields.
Industrial area.
Mining, surface mining (Tagebau).


The category interval span from to 6 where denotes city parts, 1 villages and 6 metropolises.


Haupt- oder Freizeitrouten.
The category will not be used in this case.


File with point records for traffic lights (Ampeln). The category is set to B for railroad crossings, B0 for railroad crossing without frequent traffic, F for pedestrian-only traffic lights, F0 for inactive pedestrian-only traffic lights, Zbr for drawbridges, X0 for inactive traffic lights, and otherwise (normal traffic lights), X is used.

Inactive traffic lights are currently only available in the ampeln-orig file and not processed into the final ampeln file.

File with elevation points. The Name fields denotes the elevation in meters, the category is not used.
File with sights, public buildings and other "interesting" points. Possible categories are
Unspecified sight. Use if nothing else applies.
A shopping center.

The category has usually an image attribute. The following standard images are available in bbbike:

The pseudo image px_1t may be used for invisible areas.

In area records, it is advisable to use the main entrance as the first point.

XXX To be continued


Marks the map item to be "in work". This could be rendered with an additional "in work" sign along the map item. This attribute is already handled in a couple of data files (fragezeichen, gesperrt, handicap, strassen_bab).
The map item is in a tunnel. This is already handled in sbahn, rbahn, ubahn, strassen_bab, and wasser*.

Note that not every BBBike renderer may render a tunnel specially. The Perl/Tk application has complete render support for all tunnel categories (see also the below ones). The PDFCairo renderer has simple support for tunnels (drawn as dashed lines). The PDF and GD renderers draw tunnels like normal lines, except for tunneled waterways, which are currently completely ignored. All other renderers (e.g. Mapserver) draw all tunnels like normal lines.

The map item is in a tunnel and a tunnel mound should only be drawn at the beginning of the map item.
The map item is in a tunnel and a tunnel mound should only be drawn at the end of the map item.
The map item is in a tunnel and no tunnel mounds should be drawn at all.
The map item is on a bridge. This is already handled in strassen_bab.
The map item is on an embankment (Bahn- oder Straßendamm). This means that the map item is typically over other map items. The attribute is not used yet.
The map item is in a cutting (Einschnitt). This means that the map item is typically under other map items. The attribute is not used yet.
Ignore display. Item will not be rendered, but may be used for other purposes (i.e. routing). See ignrte.
Ignore in routing. Item will not be used in routing, but may be used for other purposes (i.e. display). See igndisp.
Mark a "temporary" entry, which is non-recurring. Used in temp blockings. Currently rendered with a "calendar" sign.
Mark a temporary blocking which is active only at night. Currently rendered with a "moon" sign.
Mark a temporary blocking which is active at weekend. Currently not rendered.
Mark a temporary blocking which is recurring. Currently rendered with a "clock" sign.


Lines which are to be removed, but still should be kept as a kind of "historical documentation", may be turned into a comment with "REMOVED" as the first word. Multiple lines may be joined into one line, separated by a "---". For example:

    # REMOVED --- #: confirmed_by: me --- old entry X 1234,5678 9876,5432


    #: map: polar
    # a comment
    Dudenstr.	H 13.3857982559056,52.4850047136888 13.3822671967909,52.4849893166144 13.3765591649622,52.4849797043717 13.3721313913775,52.4849830887141 13.3708964575072,52.4850055627098
    Viktoriapark	F:P 13.3770529147335,52.4891642850551 13.376956820767,52.4876188211697 13.3778829456197,52.4875997186591

And a detailed explanation...

    Start of a directive
    #: map: polar
       Coordinate system of this file is defined as WGS84, DDD

    Start of a comment
    # a comment

(Note that spaces are insignificant in the following examples, but <TAB> and <SPACE> should be inserted)

                              List of coordinates (x,y pairs)
    Dudenstr. <TAB> H <SPACE> 13.3857982559056,52.4850047136888 13.3822671967909,52.4849893166144 13.3765591649622,52.4849797043717 13.3721313913775,52.4849830887141 13.3708964575072,52.4850055627098
    ^               ^
    Street name     Category (H = main street)

                                   List of coordinates for a polygon
    Viktoriapark <TAB> F:P <SPACE> 13.3770529147335,52.4891642850551 13.376956820767,52.4876188211697 13.3778829456197,52.4875997186591
    ^                  ^
    Name of a park     Category (F = area (polygon, Fläche),
                                 P = park)

                    Category (S = S-Bahn, A = Tariff area A)
    S1,S2,S25 <TAB> SA::Tu_ <SPACE> coordinates ...
                        Attribute (Tunnel, only draw tunnel entrance
                                   at beginning)


Some category values may change. It is likely that either the blocking and/or city category values will change, as both use digits.


Slaven Rezic <>


bbbike, Strassen.