Each record in Who's On First has a point and/or a polygon geometry. San Francisco, for example, has a polygon geometry, stored in the 85922583.geojson file (here). This polygon geometry is the default geometry of San Francisco; a record's default geometry is in any geojson file that follows the following convention:
id.geojson
Example: 85922583.geojson
However, Who's On First also stores alt-geometry (alternate geometry) records. This not only allows Who's On First to maintain flexibility in record keeping, but also allows Who's On First to house geometries from a wide variety of sources. It also allows users and services to specify which geometry to use.
At a minimum, alt-geometry filenames must conform to the following convention:
id-alt-source.geojson
Example: 85922583-alt-mapzen.geojson
The source must be listed in the whosonfirst-sources repository. This is required record-keeping that allows any user or application to trace the origin of that geometry.
Alt-geometry records must include the following minimum set of properties:
wof:id of the feature that this alt-geometry represents"feature"whosonfirst-sources repowof:id of the feature that this alt-geometry representsAn alt-geometry filename should always include the associated feature's wof:id, "alt", and the source name (with dashes in between each value).
In addition to the above rules, an alt-geometry can also include "use", "scope", and "detail". A filepath with such information would follow this convention:
id-alt-source-function-scope-detail.geojson
Where properties include:
uscensus) – The source of this geometry, which should match a file in the whosonfirst-sources repositorydisplay) – This could include: locality townspots + text) and "polygons" (e.g.: region area text) - It's important to know which "locality" features do not usually represent a single compact populated place so their mz:min_zoom can be properly set, and we can choose the correct "point" or "polygon" labeling (and possibly switch between them at different zooms)region boundary, disputed area boundaries, with some sophistication around water and land parts – e.g. option to not show territorial water parts, coastline parts, and/or inland water parts).terrestrial). This could include: territorial - Default optimized for revGeo inclusive of all marine and territorial waters (no water clipping), understood that Mapzen may have modified the original, but it's still "sourced" to the source.terrestrial - Clipped to land + terrestrial waters (e.g. clipped to ocean coastline, but not punched thru for large inland water bodies), understood that Mapzen may have modified the original, but it's still "sourced" to the source. Used for most choropleth maps.land - No marine waters, no inland waters. Used in contexts where someone doesn't want to load separate "earth" base or "water" top layers.marine - Geometric opposite of terrestrial, useful for boundary lines.zoom-10 or 1024-px)A filename with all of the above properties would look like the following example:
85668127-alt-uscensus-display-terrestrial-zoom-10.geojsonPermutations include:
85668127-alt-uscensus.geojson (common)85668127-alt-uscensus-display.geojson (common-optional)85668127-alt-uscensus-display-terrestrial.geojson (optional)85668127-alt-uscensus-display-zoom-10.geojson (optional)85668127-alt-uscensus-display-1024-px.geojson (optional)85668127-alt-uscensus-display-terrestrial-zoom-10.geojson (optional)85668127-alt-uscensus-display-terrestrial-1024-px.geojson (optional)If a default record in Who's On First has an alt-geometry record associated to it, the default record will have properties that point to it's associated alt-geometries. A snippet of these properties for the San Francisco example are shown below:
"src:geom_alt":[ "mapzen", "alt-uscensus-display-zoom-10-original", "alt-uscensus-display-terrestrial", "alt-uscensus-display-zoom-10", "alt-uscensus-display-1024-px", "alt-uscensus-display-terrestrial-zoom-10" ], Like most of Who's On First, this guideline is a work in progress and allows for future flexibility. We do not know every possible future use case for alt-geometries, but we can prepare for a variety of use cases by allowing flexibility and additions to the above rules.
Ideally, every feature in Who's On First will have at least two geometries; a default geometry that is some combination of simplification and file size and an alt-geometry that is either a source or display geometry.