From 06a360bdaeb2f85011f0718fbbc0b4ccb88af6d8 Mon Sep 17 00:00:00 2001
From: Lukas Martinelli <me@lukasmartinelli.ch>
Date: Thu, 8 Dec 2016 10:39:14 +0000
Subject: [PATCH] update docs

---
 aeroway.md             | 26 +++++++++++++
 boundary.md            | 32 ++++++++++++++++
 building.md            | 20 ++++++++++
 housenumber.md         | 16 ++++++++
 landcover.md           | 61 ++++++++++++++++++++++++++++++
 landuse.md             | 37 +++++++++++++++++++
 park.md                | 20 ++++++++++
 place.md               | 70 +++++++++++++++++++++++++++++++++++
 poi.md                 | 45 ++++++++++++++++++++++
 transportation.md      | 84 ++++++++++++++++++++++++++++++++++++++++++
 transportation_name.md | 49 ++++++++++++++++++++++++
 water.md               | 20 ++++++++++
 water_name.md          | 25 +++++++++++++
 waterway.md            | 28 ++++++++++++++
 14 files changed, 533 insertions(+)

diff --git a/aeroway.md b/aeroway.md
index 6bc54d5..140ec2e 100644
--- a/aeroway.md
+++ b/aeroway.md
@@ -46,6 +46,32 @@ Possible values:
 
 
 
+## Mapping Diagram
+![](media/mapping_aeroway.png)
+## ETL Diagram
+![](media/etl_aeroway.png)
+#aeroway
+Aeroway polygons based of OpenStreetMap [aeroways](http://wiki.openstreetmap.org/wiki/Aeroways).
+Airport buildings are contained in the **building** layer but all
+other airport related polygons can be found in the **aeroway** layer.
+## Fields
+
+### class
+
+The original value of the [`aeroway`](http://wiki.openstreetmap.org/wiki/Key:aeroway) tag.
+
+Possible values:
+
+- `aerodrome`
+- `heliport`
+- `runway`
+- `helipad`
+- `taxiway`
+- `apron`
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_aeroway.png)
 ## ETL Diagram
diff --git a/boundary.md b/boundary.md
index 4098f88..12901b9 100644
--- a/boundary.md
+++ b/boundary.md
@@ -58,6 +58,38 @@ Possible values:
 
 
 
+## Mapping Diagram
+![](media/mapping_boundary.png)
+## ETL Diagram
+![](media/etl_boundary.png)
+#boundary
+Contains administrative boundaries as linestrings (no maritime boundaries yet) as linestrings.
+Until z7 [Natural Earth data](http://www.naturalearthdata.com/downloads/10m-cultural-vectors/10m-admin-0-countries/)
+is used after which OSM boundaries ([`boundary=administrative`](http://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative)) are present from z8 to z14.
+OSM data contains all [`admin_level`](http://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative#admin_level)
+but for most styles it makes sense to just style `admin_level=2` and `admin_level=4`.
+## Fields
+
+### admin_level
+
+OSM [admin_level](http://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative#admin_level)
+indicating the level of importance of this boundary.
+The `admin_level` corresponds to the lowest `admin_level`
+the line participates in.
+At low zoom levels the Natural Earth boundaries are mapped to the equivalent admin levels.
+
+### disputed
+
+Mark with `1` if the boundary is disputed.
+
+Possible values:
+
+- `0`
+- `1`
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_boundary.png)
 ## ETL Diagram
diff --git a/building.md b/building.md
index b10094e..0b88b99 100644
--- a/building.md
+++ b/building.md
@@ -34,6 +34,26 @@ An approximated height from levels and height of the building or building:part a
 
 
 
+## Mapping Diagram
+![](media/mapping_building.png)
+## ETL Diagram
+![](media/etl_building.png)
+#building
+All [OSM Buildings](http://wiki.openstreetmap.org/wiki/Buildings). All building tags are imported ([`building=*`](http://wiki.openstreetmap.org/wiki/Key:building)). The buildings are not yet ready for 3D rendering support and any help to improve
+this is welcomed.
+## Fields
+
+### render_min_height
+
+An approximated height from levels and height of the bottom of the building or building:part after the method of Paul Norman in [OSM Clear](https://github.com/ClearTables/osm-clear). For future 3D rendering of buildings.
+
+### render_height
+
+An approximated height from levels and height of the building or building:part after the method of Paul Norman in [OSM Clear](https://github.com/ClearTables/osm-clear). For future 3D rendering of buildings.
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_building.png)
 ## ETL Diagram
diff --git a/housenumber.md b/housenumber.md
index a40d5cc..8045c42 100644
--- a/housenumber.md
+++ b/housenumber.md
@@ -23,6 +23,22 @@ Value of the [`addr:housenumber`](http://wiki.openstreetmap.org/wiki/Key:addr) t
 
 
 
+## Mapping Diagram
+![](media/mapping_housenumber.png)
+## ETL Diagram
+![](media/etl_housenumber.png)
+#housenumber
+Everything in OpenStreetMap which contains a `addr:housenumber` tag useful for labelling housenumbers on a map.
+This adds significant size to *z14*. For buildings the centroid of the building is used as housenumber.
+## Fields
+
+### housenumber
+
+Value of the [`addr:housenumber`](http://wiki.openstreetmap.org/wiki/Key:addr) tag.
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_housenumber.png)
 ## ETL Diagram
diff --git a/landcover.md b/landcover.md
index 2791b02..60b9035 100644
--- a/landcover.md
+++ b/landcover.md
@@ -116,6 +116,67 @@ Possible values:
 
 
 
+## Mapping Diagram
+![](media/mapping_landcover.png)
+## ETL Diagram
+![](media/etl_landcover.png)
+#landcover
+Landcover is used to describe the physical material at the surface of the earth. At lower zoom levels this is
+from Natural Earth data for glaciers and ice shelves and at higher zoom levels the [landcover is [implied by OSM tags](http://wiki.openstreetmap.org/wiki/Landcover). The most common use case for this layer
+  is to style wood (`class=wood`) and grass (`class=`grass`) areas.
+## Fields
+
+### class
+
+Use the **class** to assign natural colors for **landcover**.
+
+Possible values:
+
+- `farmland`
+- `ice`
+- `wood`
+- `grass`
+- `wetland`
+
+### subclass
+
+Use **subclass** to do more precise styling.
+Original value of either the
+[`natural`](http://wiki.openstreetmap.org/wiki/Key:natural),
+[`landuse`](http://wiki.openstreetmap.org/wiki/Key:landuse),
+,[`leisure`](http://wiki.openstreetmap.org/wiki/Key:leisure),
+or [`wetland`](http://wiki.openstreetmap.org/wiki/Key:wetland) tag.
+
+Possible values:
+
+- `allotments`
+- `farm`
+- `farmland`
+- `orchard`
+- `plant_nursery`
+- `vineyard`
+- `grass`
+- `grassland`
+- `meadow`
+- `forest`
+- `village_green`
+- `recreation_ground`
+- `park`
+- `wetland`
+- `grassland`
+- `bog`
+- `swamp`
+- `wet_meadow`
+- `marsh`
+- `reedbed`
+- `saltern`
+- `tidalflat`
+- `saltmarsh`
+- `mangrove`
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_landcover.png)
 ## ETL Diagram
diff --git a/landuse.md b/landuse.md
index cacfe54..f6e32df 100644
--- a/landuse.md
+++ b/landuse.md
@@ -68,6 +68,43 @@ Possible values:
 
 
 
+## Mapping Diagram
+![](media/mapping_landuse.png)
+## ETL Diagram
+![](media/etl_landuse.png)
+#landuse
+Landuse is used to describe use of land by humans.At lower zoom levels this is
+from Natural Earth data for residential (urban) areas and at higher zoom levels mostly OSM `landuse` tags.
+## Fields
+
+### class
+
+Use the **class** to assign special colors to areas.
+Original value of either the
+[`amenity`](http://wiki.openstreetmap.org/wiki/Key:amenity),
+[`landuse`](http://wiki.openstreetmap.org/wiki/Key:landuse),
+or [`leisure`](http://wiki.openstreetmap.org/wiki/Key:leisure) tag.
+
+Possible values:
+
+- `school`
+- `university`
+- `kindergarten`
+- `college`
+- `library`
+- `hospital`
+- `railway`
+- `cemetery`
+- `military`
+- `residential`
+- `commercial`
+- `industrial`
+- `retail`
+- `stadium`
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_landuse.png)
 ## ETL Diagram
diff --git a/park.md b/park.md
index eacb86c..9d2fbd7 100644
--- a/park.md
+++ b/park.md
@@ -34,6 +34,26 @@ Possible values:
 
 
 
+## Mapping Diagram
+![](media/mapping_park.png)
+## ETL Diagram
+![](media/etl_park.png)
+#park
+The park layer contains parks from OpenStreetMap tagged with either [`boundary=national_park`](http://wiki.openstreetmap.org/wiki/Tag:boundary%3Dnational_park) or [`leisure=nature_reserve`](http://wiki.openstreetmap.org/wiki/Tag:leisure%3Dnature_reserve).
+## Fields
+
+### class
+
+Use the **class** to differentiate between different parks.
+
+Possible values:
+
+- `national_park`
+- `nature_reserve`
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_park.png)
 ## ETL Diagram
diff --git a/place.md b/place.md
index 4ddb428..9bc3ab8 100644
--- a/place.md
+++ b/place.md
@@ -134,6 +134,76 @@ The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the POI.
 
 
 
+## Mapping Diagram
+![](media/mapping_place.png)
+## ETL Diagram
+![](media/etl_place.png)
+#place
+The place layer consists out of [countries](http://wiki.openstreetmap.org/wiki/Tag:place%3Dcountry),
+[states](http://wiki.openstreetmap.org/wiki/Tag:place%3Dstate) and [cities](http://wiki.openstreetmap.org/wiki/Key:place).
+Apart from the roads this is also one of the more important layers to create a beautiful map.
+We suggest you use different font styles and sizes to create a text hierarchy.
+## Fields
+
+### name_en
+
+The English `name:en` value or local `name` if not available.
+
+### capital
+
+The **capital** field marks the
+[`admin_level`](http://wiki.openstreetmap.org/wiki/Tag:boundary%3Dadministrative#admin_level)
+of the boundary the place is a capital of.
+
+Possible values:
+
+- `2`
+- `4`
+
+### class
+
+description: |
+    Original value of the
+    [`place`](http://wiki.openstreetmap.org/wiki/Key:place) tag.
+    Distinguish between continents, countries, states and
+    places like settlements or smaller entities.
+    Use **class** to separately style the different places and build
+    a text hierarchy according to their importance.
+values:
+- continent
+- country
+- state
+- city
+- town
+- village
+- hamlet
+- suburb
+- neighbourhood
+- isolated_dwelling
+
+### rank
+
+Countries, states and the most important cities all have a
+**rank** to boost their importance on the map.
+The **rank** field for counries and states ranges from
+`1` to `6` while the **rank** field for cities ranges from
+`1` to `10` for the most important cities
+and continues from `10` serially based on the
+local importance of the city (derived from population and city class).
+You can use the **rank** to limit density of labels or improve
+the text hierarchy.
+The rank value is a combination of the Natural Earth
+`scalerank`, `labelrank` and `datarank` values for countries
+and states and for cities consists out of a shifted
+Natural Earth `scalerank` combined with a local rank
+within a grid for cities that do not have a Natural Earth `scalerank`.
+### name
+
+The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the POI.
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_place.png)
 ## ETL Diagram
diff --git a/poi.md b/poi.md
index 1adf567..4d69606 100644
--- a/poi.md
+++ b/poi.md
@@ -84,6 +84,51 @@ tag.  Use this to do more precise styling.
 
 
 
+## Mapping Diagram
+![](media/mapping_poi.png)
+## ETL Diagram
+![](media/etl_poi.png)
+#poi
+[Points of interests](http://wiki.openstreetmap.org/wiki/Points_of_interest) containing
+a of a variety of OpenStreetMap tags. Mostly contains amenities, sport, shop and tourist POIs.
+## Fields
+
+### class
+
+More general classes of POIs. If there is no more general `class` for the `subclass`
+this field will contain the same value as `subclass`.
+But for example for schools you only need to style the class `school` to filter the subclasses `school`
+and `kindergarten`. Or use the class `shop` to style all shops.
+
+### name_en
+
+The english `name:en` value if available.
+
+### name
+
+The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the POI.
+
+### rank
+
+The POIs are ranked ascending according to their importance within a grid. The `rank` value shows the
+local relative importance of a POI within it's cell in the grid. This can be used to reduce label density at z14.
+Since all POIs already need to be contained at `z14` you can use `less than rank=10` epxression to limit
+POIs. At some point like z17 you can show all POIs.
+
+### subclass
+
+Original value of either the
+[`amenity`](http://wiki.openstreetmap.org/wiki/Key:amenity),
+[`leisure`](http://wiki.openstreetmap.org/wiki/Key:leisure),
+[`landuse`](http://wiki.openstreetmap.org/wiki/Key:landuse),
+[`sport`](http://wiki.openstreetmap.org/wiki/Key:sport),
+[`tourism`](http://wiki.openstreetmap.org/wiki/Key:tourism)
+or [`shop`](http://wiki.openstreetmap.org/wiki/Key:shop)
+tag.  Use this to do more precise styling.
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_poi.png)
 ## ETL Diagram
diff --git a/transportation.md b/transportation.md
index bce11a3..9ad01cc 100644
--- a/transportation.md
+++ b/transportation.md
@@ -162,6 +162,90 @@ Possible values:
 
 
 
+## Mapping Diagram
+![](media/mapping_transportation.png)
+## ETL Diagram
+![](media/etl_transportation.png)
+#transportation
+**transportation** contains roads and railways.
+This layer is directly derived from the OSM road hierarchy.
+Only at zoom level 4 to 6 some major highways from Natural Earth
+are used.
+It contains all roads from motorways to primary, secondary and
+tertiary roads to residential roads and
+foot paths. Styling the roads is the most essential part of the map.
+The `transportation` layer also contains polygons for things like plazas.
+## Fields
+
+### brunnel
+
+Mark whether way is a tunnel or bridge.
+
+Possible values:
+
+- `bridge`
+- `tunnel`
+- `ford`
+
+### ramp
+
+Mark with `1` whether way is a ramp (link or steps)
+or not with `0`.
+
+Possible values:
+
+- `0`
+- `1`
+
+### class
+
+Distinguish between more and less important roads or railways.
+Class is derived from the value of the
+[`highway`](http://wiki.openstreetmap.org/wiki/Key:highway) or
+[`railway`](http://wiki.openstreetmap.org/wiki/Key:railway) tag.
+
+Possible values:
+
+- `motorway`
+- `trunk`
+- `primary`
+- `secondary`
+- `tertiary`
+- `minor`
+- `service`
+- `track`
+- `path`
+- `raceway`
+- `rail`
+- `transit`
+
+### service
+
+Original value of the [`service`](http://wiki.openstreetmap.org/wiki/Key:service) tag.
+
+Possible values:
+
+- `spur`
+- `yard`
+- `siding`
+- `crossover`
+- `driveway`
+- `alley`
+- `parking_aisle`
+
+### oneway
+
+Mark with `1` whether way is a oneway (in the direction of the way)
+or not with `0`.
+
+Possible values:
+
+- `0`
+- `1`
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_transportation.png)
 ## ETL Diagram
diff --git a/transportation_name.md b/transportation_name.md
index 5ea2d16..bf5f53c 100644
--- a/transportation_name.md
+++ b/transportation_name.md
@@ -89,6 +89,55 @@ The OSM [`name`](http://wiki.openstreetmap.org/wiki/Highways#Names_and_reference
 
 
 
+## Mapping Diagram
+![](media/mapping_transportation_name.png)
+## ETL Diagram
+![](media/etl_transportation_name.png)
+#transportation_name
+This is the layer for labelling the highways. Only highways that are named `name=*` and are long enough
+to place text upon appear. The OSM roads are stitched together if they contain the same name
+to have better label placement than having many small linestrings.
+For motorways you should use the `ref` field to label them while for other roads you should use `name`.
+## Fields
+
+### ref
+
+The OSM [`ref`](http://wiki.openstreetmap.org/wiki/Key:ref) tag of the motorway or road.
+
+### ref_length
+
+Length of the `ref` field. Useful for having a shield icon as background for labeling motorways.
+
+### class
+
+Distinguish between more and less important roads.
+
+Possible values:
+
+- `motorway`
+- `trunk`
+- `primary`
+- `secondary`
+- `tertiary`
+- `minor`
+- `service`
+- `track`
+- `path`
+- `raceway`
+- `rail`
+- `transit`
+
+### network
+
+The OSM [`network`](http://wiki.openstreetmap.org/wiki/Key:network) tag of the road.
+
+### name
+
+The OSM [`name`](http://wiki.openstreetmap.org/wiki/Highways#Names_and_references) value of the highway.
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_transportation_name.png)
 ## ETL Diagram
diff --git a/water.md b/water.md
index 537470a..bc3cf4d 100644
--- a/water.md
+++ b/water.md
@@ -34,6 +34,26 @@ Either `ocean`, `lake` or `river`.
 
 
 
+## Mapping Diagram
+![](media/mapping_water.png)
+## ETL Diagram
+![](media/etl_water.png)
+#water
+Water polygons representing oceans and lakes. Covered watered areas are excluded (`covered=yes`).
+Until z6 all water originates from Natural Earth. To get a more correct display of the south pole you should also
+style the covering ice shelves over the water.
+Water from OpenStreetMap after z7 is split into many smaller polygons to improve rendering performance.
+This however can lead to less rendering options in clients since these boundaries show up. So you might not be
+able to use border styling for ocean water features.
+## Fields
+
+### class
+
+Either `ocean`, `lake` or `river`.
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_water.png)
 ## ETL Diagram
diff --git a/water_name.md b/water_name.md
index 722ef7b..794e30b 100644
--- a/water_name.md
+++ b/water_name.md
@@ -44,6 +44,31 @@ At the moment only `lake` since no ocean parts are labelled. *Reserved for futur
 
 
 
+## Mapping Diagram
+![](media/mapping_water_name.png)
+## ETL Diagram
+![](media/etl_water_name.png)
+#water_name
+Lake center lines for labelling lake bodies.
+This is based of the [osm-lakelines](https://github.com/lukasmartinelli/osm-lakelines) project
+which derives nice centerlines from OSM water bodies. Only the most important lakes contain labels.
+## Fields
+
+### name_en
+
+The english `name:en` value if available.
+
+### name
+
+The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the water body.
+
+### class
+
+At the moment only `lake` since no ocean parts are labelled. *Reserved for future use*.
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_water_name.png)
 ## ETL Diagram
diff --git a/waterway.md b/waterway.md
index 1306ffd..7080cb6 100644
--- a/waterway.md
+++ b/waterway.md
@@ -50,6 +50,34 @@ Can be one of [`stream`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dstrea
 
 
 
+## Mapping Diagram
+![](media/mapping_waterway.png)
+## ETL Diagram
+![](media/etl_waterway.png)
+#waterway
+Rivers based of OpenStreetMap [waterways](http://wiki.openstreetmap.org/wiki/Waterways) for *z9* to *z14*
+and Natural Earth rivers and lake centerlines from *z3* to *z8*.
+Linestrings without a name or which are too short are filtered
+out at low zoom levels. Waterways do no not have a `subclass` field.
+## Fields
+
+### name
+
+The OSM [`name`](http://wiki.openstreetmap.org/wiki/Key:name) value of the waterway.
+The `name` field is empty for NaturalEarth data until **z9** when OSM data is used.
+
+### class
+
+The original value of the [`waterway`](http://wiki.openstreetmap.org/wiki/Key:waterway) tag.
+Can be one of [`stream`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dstream),
+[`river`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Driver),
+[`canal`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dcanal),
+[`drain`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Ddrain),
+[`ditch`](http://wiki.openstreetmap.org/wiki/Tag:waterway%3Dditch)`.
+
+
+
+
 ## Mapping Diagram
 ![](media/mapping_waterway.png)
 ## ETL Diagram