Who's On First

https://whosonfirst.org/docs/
Admin
Who's On First is a gazetteer containing stable identifiers and properties for millions of places...
Tokens:28,635
Snippets:456
Trust Score:9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example Alt-Geometry Filename

Source: https://whosonfirst.org/docs/geometries/alt

This example demonstrates a complete alt-geometry filename incorporating all optional properties: source, function, scope, and detail.

```text
85668127-alt-uscensus-display-terrestrial-zoom-10.geojson
```

--------------------------------

### Install WOF Utilities

Source: https://whosonfirst.org/docs/processes/san-francisco-neighbourhoods

Run the `install` script within the `whosonfirst-utils` repository to set up necessary dependencies for data processing. This script is typically executed after cloning the repository.

```bash
install
```

--------------------------------

### Superseding Record Example

Source: https://whosonfirst.org/docs/hierarchies

This example shows the properties for a record that supersedes an older record. The 'wof:supersedes' list contains the ID of the older record.

```json
"wof:superseded_by": [],
"wof:supersedes": [85892915]
```

--------------------------------

### Yugoslavia EDTF Examples

Source: https://whosonfirst.org/docs/dates

Examples of EDTF date strings for various Yugoslavian entities.

```text
wof:name="Kingdom of Yugoslavia" edtf:inception="1918" edtf:cessation="1941" 
```

```text
wof:name="Socialist Federal Republic of Yugoslavia" edtf:inception="1945-11-29" edtf:cessation="1991-06~/1995-12~" 
```

```text
wof:name="Bosnia and Herzegovina" edtf:inception="1992-03~/1992-04~" 
```

--------------------------------

### Name Conversion Output Example

Source: https://whosonfirst.org/docs/names

Shows the expected output from the Python name conversion script, illustrating the transformations between different naming conventions.

```text
fin_p fin_x_prefered fin-x-prefered fin_x_prefered fin_p eng_s eng_x_colloquial eng-x-colloquial eng_x_colloquial eng_s unk_v und_x_variant und-x-variant und_x_variant unk_v
```

--------------------------------

### Query point-in-polygon service via cURL

Source: https://whosonfirst.org/docs/spr

Example command to query the go-whosonfirst-pip-v2 tool and format the JSON output.

```bash
curl -s 'http://localhost:8080/?latitude=37.787221&longitude=-122.400098&placetype=locality' | python -mjson.tool
{
    "places": [
        {
            "wof:id": 85922583,
            "wof:parent_id": 102087579,
            "wof:name": "San Francisco",
            "wof:placetype": "locality",
            "wof:country": "US",
            "wof:repo": "whosonfirst-data",
            "wof:path": "859/225/83/85922583.geojson",
            "wof:superseded_by": [],
            "wof:supersedes": [],
            "mz:uri": "https://whosonfirst.mapzen.com/data/859/225/83/85922583.geojson",
            "mz:latitude": 37.778008,
            "mz:longitude": -122.43127200000001,
            "mz:min_latitude": 37.639830000000003,
            "mz:min_longitude": -123.17382499999999,
            "mz:max_latitude": 37.929824000000004,
            "mz:max_longitude": -122.28178,
            "mz:is_current": 1,
            "mz:is_ceased": -1,
            "mz:is_deprecated": 0,
            "mz:is_superseded": 0,
            "mz:is_superseding": 0,
            "wof:lastmodified": 1501271725
        }
    ]
}
```

--------------------------------

### Superseded Record Example

Source: https://whosonfirst.org/docs/hierarchies

This example shows the properties for a record that has been superseded by a newer record. The 'wof:superseded_by' list contains the ID of the new record.

```json
"wof:superseded_by": [102147495],
"wof:supersedes": []
```

--------------------------------

### Clone WOF Repositories with Git

Source: https://whosonfirst.org/docs/processes/san-francisco-neighbourhoods

Use `git checkout` to clone the necessary Who's On First data repositories from GitHub. Ensure you have Git installed and configured.

```bash
git checkout
```

--------------------------------

### Common Alt-Geometry Filename Permutations

Source: https://whosonfirst.org/docs/geometries/alt

These examples show common and optional permutations of alt-geometry filenames, illustrating how different combinations of properties affect the naming convention.

```text
85668127-alt-uscensus.geojson
```

```text
85668127-alt-uscensus-display.geojson
```

```text
85668127-alt-uscensus-display-terrestrial.geojson
```

```text
85668127-alt-uscensus-display-zoom-10.geojson
```

```text
85668127-alt-uscensus-display-1024-px.geojson
```

```text
85668127-alt-uscensus-display-terrestrial-zoom-10.geojson
```

```text
85668127-alt-uscensus-display-terrestrial-1024-px.geojson
```

--------------------------------

### WOE Name and Alias Example

Source: https://whosonfirst.org/docs/names

Illustrates the WOE distinction between a primary name and its aliases, including language and type information.

```text
Name:  Montréal  Language: FRE Alias (ENG_P): Montreal Alias (KOR_Q): 몬트리올 
```

--------------------------------

### Who's On First Name Structure Example

Source: https://whosonfirst.org/docs/names

Demonstrates the JSON structure for storing multiple names, aliases, and translations for a place, adhering to RFC 5646 subtags for language and script.

```json
{
	"wof:name": "Montreal",
	"wof:lang": [ "eng", "fre" ],
	"name:eng_p": "Montreal",
	"name:eng_a": "YMQ",
	"name:fre_p": "Montréal",
	"name:kor_p": "몬트리올",
}
```

--------------------------------

### British North America EDTF Example

Source: https://whosonfirst.org/docs/dates

Example of EDTF inception and cessation dates for British North America.

```text
wof:name="British North America" edft:inception="1783~" edtf:cessation="1907" 
```

--------------------------------

### Define Controlled Properties

Source: https://whosonfirst.org/docs/properties/wof

Example of a JSON array defining properties that should be protected from automated updates.

```json
    "wof:controlled":[         "wof:hierachy",         "wof:parent_id"     ] 
```

--------------------------------

### Define Venue Hours

Source: https://whosonfirst.org/docs/properties/mz

Example of the mz:hours property structure using 24-hour time format.

```json
"mz:hours": { 	"mon": { 		"open": "07:30", 		"close": "19:00" 	}, 	"tue": { 		"open": "08:30", 		"close": "22:00" 	} }
```

--------------------------------

### Descendant Hierarchy Before Parent Import

Source: https://whosonfirst.org/docs/processes/wof-life-cycle

This example shows the `wof:hierarchy` property of a descendant record before its parent (a new county) has been imported into Who's On First. Notice the absence of a `county_id`.

```json
"wof:hierarchy":[         {             "continent_id":102191575,             "country_id":85633793,             "region_id":85688637,             "locality_id":85922583         }     ], 
```

--------------------------------

### Descendant Hierarchy After Parent Import

Source: https://whosonfirst.org/docs/processes/wof-life-cycle

This example shows the `wof:hierarchy` property of a descendant record after its parent (a new county) has been imported. The `county_id` is now present, reflecting the updated hierarchy.

```json
"wof:hierarchy":[         {             "continent_id":102191575,             "country_id":85633793,             "region_id":85688637,             "county_id":102087579,             "locality_id":85922583         }     ], 
```

--------------------------------

### RFC 5646 Tag Conversion Examples

Source: https://whosonfirst.org/docs/names

Demonstrates the conversion of Who's On First style RFC 5646 tags to standard RFC 5646 tags by replacing underscores with dashes and converting three-letter language codes to two-letter codes.

```text
eng_x_preferred → en-x-preferred fre_ca_x_variant → fr-ca-x-variant
```

--------------------------------

### Category Class Property Example

Source: https://whosonfirst.org/docs/categories

Defines the 'class' property for a category, specifying its point of view and class membership. Strings are parsed left-to-right as POINT-OF-VIEW > CLASS.

```json
"name": "restaurant", "class": [ "consensus:eating", "tourist:eating", "local:nomnomnom" ]
```

--------------------------------

### Collect Neighbourhood GeoJSON with Python Script

Source: https://whosonfirst.org/docs/processes/san-francisco-neighbourhoods

Execute the `WOF-csv-to-feature-collection.py` script to gather neighbourhood records into a single GeoJSON file. Update filepaths and the locality ID to match your local setup and desired region. This script is part of the `whosonfirst-utils` repository.

```python
python WOF-csv-to-feature-collection -p /usr/local/mapzen/whosonfirst-data/data -c /usr/local/mapzen/whosonfirst-data/meta/WOF-neighbourhood-latest.csv --aliases /usr/local/mapzen/whosonfirst-properties/aliases/property_aliases.json -o ~/Desktop/SF_Neighbourhoods.geojson --slim --slim-template external_editor -f 85922583
```

--------------------------------

### WOF Property Documentation

Source: https://whosonfirst.org/docs/properties/wof

Detailed documentation for individual Who's On First (WOF) properties.

```APIDOC
## WOF Property: abbreviation

### Description
A two-letter country code from ISO 3166.

### Property Type
String
```

```APIDOC
## WOF Property: belongsto

### Description
The (unique) set of all ancestors, as an array (list) of WOF IDs.

### Property Type
Array of Integers
```

```APIDOC
## WOF Property: breaches

### Description
Records of the same placetype that intersect the current record, as an array (list) of WOF IDs.

### Property Type
Array of Integers
```

```APIDOC
## WOF Property: concordances

### Description
A hash containing identifiers from other data sources. See also: other people's concordances

### Property Type
Object
```

```APIDOC
## WOF Property: concordances_alt

### Description
A dictionary of lists, used if a record has more than one identifier for a single data source. Contains identifiers not present in the `wof:concordances` property.

### Property Type
Object
```

```APIDOC
## WOF Property: controlled

### Description
A list of Who's On First properties that should be assumed to have been edited by an actual human and should not be updated by automated processes.

### Example
```json
{
  "wof:controlled": [
    "wof:hierachy",
    "wof:parent_id"
  ]
}
```

### Property Type
Array of Strings
```

```APIDOC
## WOF Property: coterminous

### Description
Links two or more records with overlapping or identical geometries that serve separate functions, but are essentially the same "place" - see Cuidad de México. Think "city-state".

### Property Type
Array of Integers
```

```APIDOC
## WOF Property: country

### Description
A two-letter country code from ISO 3166.

### Property Type
String
```

```APIDOC
## WOF Property: created

### Description
An auto-generated, non-editable Unix epoch timestamp integer.

### Property Type
Integer
```

```APIDOC
## WOF Property: geomhash

### Description
An auto-generated, non-editable MD5 string of the geometry JSON.

### Property Type
String
```

```APIDOC
## WOF Property: hierarchy

### Description
A list of hashes, where each object is the list of ancestors.

### Property Type
Array of Objects
```

```APIDOC
## WOF Property: id

### Description
The record's unique numeric integer identifier that are typically derived from Brooklyn Integers.

### Property Type
Integer
```

```APIDOC
## WOF Property: lang

### Description
An ISO-639-3 language identifiers. These represent the common, or preferred, languages spoken in the location of the corresponding WOF record. **DEPRECATED**.

### Property Type
String
```

```APIDOC
## WOF Property: lang_x_official

### Description
One or more ISO-639-3 language identifiers. These represent the officially recognized languages of the location of the corresponding WOF record.

### Property Type
Array of Strings
```

```APIDOC
## WOF Property: lang_x_spoken

### Description
One or more ISO-639-3 language identifiers. These represent the languages, inclusive of official languages, spoken in the location of the corresponding WOF record.

### Property Type
Array of Strings
```

```APIDOC
## WOF Property: lastmodified

### Description
A Unix epoch timestamp integer.

### Property Type
Integer
```

```APIDOC
## WOF Property: name

### Description
An English UTF-7 transliterated representation of the name. See also: whosonfirst-names

### Property Type
String
```

```APIDOC
## WOF Property: parent_id

### Description
An integer WOF ID of the direct parent record. If a record has more than one parent, special values are used: -1 (unknown), -2 (shrug), -3 (contested), -4 (multiple legal parents).

### Property Type
Integer
```

```APIDOC
## WOF Property: placetype

### Description
A string placetype.

### Property Type
String
```

```APIDOC
## WOF Property: placetype_alt

### Description
A list of string placetypes denoting alternate representations of a place.

### Property Type
Array of Strings
```

```APIDOC
## WOF Property: placetype_local

### Description
What locals consider the placetype to be (string value).

### Property Type
String
```

```APIDOC
## WOF Property: population

### Description
An integer value to represent the most current, known population of a place. (related: `src:population`)

### Property Type
Integer
```

```APIDOC
## WOF Property: population_rank

### Description
An aggregated integer, 0 to 14, representing population ranges.

### Property Type
Integer
```

```APIDOC
## WOF Property: statistical_gore

### Description
An optional boolean value that, when true, represents an “area” of unincorporated status without self-governance.

### Property Type
Boolean
```

```APIDOC
## WOF Property: superseded_by

### Description
An array (a list) of WOF IDs that have superseded the WOF record.

### Property Type
Array of Integers
```

```APIDOC
## WOF Property: supersedes

### Description
An array (a list) of WOF IDs that the record supersedes.

### Property Type
Array of Integers
```

```APIDOC
## WOF Property: tags

### Description
An array (a list) of tags.

### Property Type
Array of Strings
```

--------------------------------

### Sub-category Category Property Example

Source: https://whosonfirst.org/docs/categories

Defines the 'category' property for a sub-category, specifying its point of view, class, and category membership. Strings are parsed left-to-right as POINT-OF-VIEW > CLASS > CATEGORY.

```json
"name": "afghan", "category": [ "consensus:eating:restaurant", "local:nomnomnom:restaurant" ]
```

--------------------------------

### Define Shapefile Schema Interface

Source: https://whosonfirst.org/docs/shapefiles

This interface defines the structure and data types for the Who’s On First shapefile distribution.

```go
type ShapefileSchema interface {
	id() integer
	parent_id() integer
	name() string
	placetype() string
	country() string
	repo() string
	lat() float
	lon() float
	min_lat() float
	min_lon() float
	max_lat() float
	max_lon() float
	modified() date
	name_ara() string
	name_ben() string
	name_deu() string
	name_eng() string
	name_ell() string
	name_fas() string
	name_fra() string
	name_heb() string
	name_hin() string
	name_hun() string
	name_ind() string
	name_ita() string
	name_jpn() string
	name_kor() string
	name_nld() string
	name_pol() string
	name_por() string
	name_rus() string
	name_spa() string
	name_swe() string
	name_tur() string
	name_ukr() string
	name_urd() string
	name_vie() string
	name_zho() string
	gn_id() integer
	wd_id() integer
	concord_id() string
	concord_ke() string
	iso_code() string
	hasc_id() string
	country_id() integer
	region_id() integer
	county_id() integer
	population() integer
	placetype_local() string
	is_funky() integer
	min_zoom() float
	max_zoom() float
	min_label() float
	max_label() float
	geom_src() string
}
```

--------------------------------

### Representing hierarchy as a list of full hierarchy objects

Source: https://whosonfirst.org/docs/placetypes

Stores the entire hierarchy as a list of complete objects, ensuring explicitness and ease of comparison at the cost of increased file size.

```json
"wof:hierarchy": [ 	{ "neighbourhood_id": 9997, "locality_id": 9997, "metro_id": 9998, "county_id": 9998, "region_id": 9998, "country_id": 9998, "continent_id": 9998 }, 	{ "neighbourhood_id": 9997, "locality_id: 9997, "metro_id": 9999, "county_id": 9999, "region_id": 9999, "country_id": 9999, "continent_id": 9999 } ]
```

--------------------------------

### Request Word Count from Wikipedia API

Source: https://whosonfirst.org/docs/processes/wikipedia-concordances

This Python code uses the `requests` library to get the word count for a Wikipedia search term. The `name` variable must be set prior to running.

```python
request_API= ("https://en.wikipedia.org/w/api.php?action=query&list=search&srsearch=%s&srprop=wordcount&srlimit=1&format=json" %name)
result_request=requests.get(request_API)
```

--------------------------------

### Minimum Viable Properties Dictionary

Source: https://whosonfirst.org/docs/properties

This dictionary represents the essential properties needed to identify and display a place. It includes an ID, name, full name, place type, parent ID, and quality/score placeholders.

```json
{
  "wof:id": 85922583,
  "wof:name": "San Francisco",
  "wof:fullname": "San Francisco, California US",
  "wof:placetype": "locality",
  "wof:parent_id": 85688637,
  "wof:quality": 9,
  "wof:score": 100

}
```

--------------------------------

### WOF Data Attributes

Source: https://whosonfirst.org/docs/processes/san-francisco-neighbourhoods

This section outlines the various attributes available in Who's On First records and their specific purposes.

```APIDOC
## WOF Data Attributes

### Description
This section details various attributes used in Who's On First (WOF) data records, explaining their purpose and usage.

### Attributes

- **'is_landuse_aoi'** (boolean) - Used to signify an "area of interest" land use, different than the `wof:placetype` would suggest.
- **'supersedes'** (string) - The attribute that will be used for the `wof:supersedes` field. Required for all files that supersede another WOF record.
- **'superseded_by'** (string) - The attribute that will be used for the `wof:superseded_by` field. Required for all files that are superseded by another WOF record.
- **'deprecated'** (date) - The attribute that will be used for the `edtf:deprecated` field. A date field _(YYYY-MM-DD)_ used to signify when this record was determined to be incorrect. Required for all deprecated files.
- **'cessation'** (date) - The attribute that will be used for the `edtf:cessation` field. A date field _(YYYY-MM-DD)_ used to signify when this record was determined to be no longer valid. Also requires `mz:is_current` to be set to '0'.
- **'eng_preferred_name'** (string) - Preferred alternative names for a feature.
- **'eng_variant_name'** (string) - Variant alternative names for a feature.
- **'max_zoom'** (integer) - Maximum zoom level at which feature labels appear on a map. Required for all new features.
- **'min_zoom'** (integer) - Minimum zoom level at which feature labels appear on a map. Required for all new features.
- **'lbl_latitude'** (decimal) - A decimal value of a feature's Y coordinate, derived from MapShaper. Used for label placement.
- **'lbl_longitude'** (decimal) - A decimal value of a feature's X coordinate, derived from MapShaper. Used for label placement.
- **'rev_lat'** (decimal) - Equal to the `lbl_latitude` value. Used to rebuild the feature's hierarchy.
- **'rev_long'** (decimal) - Equal to the `lbl_longitude` value. Used to rebuild the feature's hierarchy.
- **'is_funky'** (boolean) - Optional flag.
- **'is_hard_boundary'** (boolean) - Optional flag.
- **'is_official'** (boolean) - Optional flag.
- **'tier_locality'** (string) - Optional locality tier information.
- **'country_id'** (integer) - The `wof:id` of the feature's parent country.
- **'region_id'** (integer) - The `wof:id` of the feature's parent region.
- **'locality_id'** (integer) - The `wof:id` of the feature's parent locality.
- **'WOF_country'** (string) - Usually equal to the ISO code, this is a two-digit key representing the country. Required for all features.
- **'iso_country'** (string) - Set by the International Organization for Standardization, this is a two-digit key representing the country. Required for all features.
- **'src_geom'** (string) - Optional. Contains the source name of the feature's geometry.
- **'mz_note'** (string) - Optional. Contains information about the given feature.
```

--------------------------------

### Who's On First Special ISO Country Codes

Source: https://whosonfirst.org/docs/placetypes

Who's On First uses specific codes for special cases: 'XK' for Kosovo (following Geonames), 'XN' for Null Island, 'XX' for disputed territories, 'XY' for undetermined ISO countries, and 'XZ' for places equivalent to wof:parent_id=-2.

```text
XK: Kosovo
XN: Null Island
XX: Disputed territory
XY: Undetermined ISO country
XZ: Equivalent to wof:parent_id=-2
```

--------------------------------

### Define StandardPlacesResult interface in Go

Source: https://whosonfirst.org/docs/spr

The interface contract required for software packages to support the Standard Places Response.

```go
type StandardPlacesResult interface {
	Id() string
	ParentId() string
	Name() string
	Placetype() string
	Country() string
	Repo() string
	Path() string
	URI() string
	Latitude() float64
	Longitude() float64
	MinLatitude() float64
	MinLongitude() float64
	MaxLatitude() float64
	MaxLongitude() float64
	IsCurrent() flags.ExistentialFlag
	IsCeased() flags.ExistentialFlag
	IsDeprecated() flags.ExistentialFlag
	IsSuperseded() flags.ExistentialFlag
	IsSuperseding() flags.ExistentialFlag
	SupersededBy() []int64
	Supersedes() []int64
}
```

--------------------------------

### Update Deprecated WOF Feature Properties

Source: https://whosonfirst.org/docs/processes/wof-life-cycle

For features that never existed in Who's On First (due to errors), an `edtf:deprecated` date is applied and `mz:is_current` is set to 0.

```json
"edtf:deprecated": 2016-10-01, ... "mz:is_current":0, 
```

--------------------------------

### Retrieve Neighbourhoods in San Francisco using API

Source: https://whosonfirst.org/docs

Use this cURL command to retrieve descendant places, specifically neighbourhoods in San Francisco, by providing a parent ID and API key.

```shell
curl -X GET 'https://places.mapzen.com/v1?method=whosonfirst.places.getDescendants&id=85922583&extras=geom:,mz:uri&api_key=your-mapzen-api-key'
```
Tokens:
Raw