Locations
Locations are unique places or positions. A named town or city can be a Location, as can an administrative area like a county, district or governorate. In fact, anything that can be drawn on a map can be a Location: a specific point, a section of a road, a military line of control, and so on.
Location: Summary of attributes
The table below summarizes the following dimensions of Locations:
Attribute label: a human readable label for the attribute
Status: whether the attribute is optional or required in a claim
Data type: the sort of data that can be entered into the attribute
Key name: a standardized name that simplifies attribute use in SFM databases
Attribute label |
Status |
Data type |
Key name |
|---|---|---|---|
status:meta |
required |
string |
|
internal_comments:meta |
optional |
string |
|
researcher:meta |
required |
string |
|
id:entity |
required |
string<->uuid |
|
location:humane_id:qa |
optional |
string |
|
name:annotation |
required |
string |
|
origin_id:location |
required |
string |
|
geo_type:qa |
optional |
string |
|
origin:location |
required |
string |
|
geometry:ref:entity |
required |
string<->uuid |
|
citation:refs:claim |
optional |
strings<->uuids |
|
country:annotation |
optional |
string |
|
location:explicit_parent:annotation |
optional |
string |
|
first_precise:range |
optional |
string-date |
|
last_precise:range |
optional |
string-date |
|
first_imprecise:range |
optional |
string-date |
|
last_imprecise:range |
optional |
string-date |
|
starting:range |
optional |
YN<->bool |
|
ending:range |
optional |
YN<->bool |
|
starting_context:range |
optional |
string |
|
ending_context:range |
optional |
string |
|
location:admin_level:qa |
optional |
string |
|
location:admin_level_10:qa |
optional |
string |
|
location:admin_level_9:qa |
optional |
string |
|
location:admin_level_8:qa |
optional |
string |
|
location:admin_level_7:qa |
optional |
string |
|
location:admin_level_6:qa |
optional |
string |
|
location:admin_level_5:qa |
optional |
string |
|
location:admin_level_4:qa |
optional |
string |
|
location:admin_level_3:qa |
optional |
string |
|
location:admin_level_2:qa |
optional |
string |
|
public_notes:meta |
optional |
string |
|
type:entity |
required |
string |
|
Location: Details of attributes
This section contains further information about each attribute, including descriptions, examples of use, and Guidance on use.
status:meta
Description
A field that classifies the data.
Attribute type
Text string
Status
This attribute is optional.
Key name
:claim/statuses
Example of use
accepted, conflict, work_needed, issue
Guidance on use
Data are marked accepted when all of the data can be entered in accordance with the guidance of this handbook. The conflict flag is used whenever there is a conflicts with another location and a review shows it to be the incorrect or false location. A public_notes:meta should always accompany any conflict flag.
If the data itself cannot be brought into the SFM standard the flag issue should be used. Finally, if it cannot be established whether a location should be flagged as accepted or conflict then the flag work_needed should be used as additional research is needed.
researcher:meta
Description
Field for initials or other identifier of researcher who last entered data for the location.
Attribute type
Text string
Status
This attribute is required.
Key name
:meta/researchers
Example of use
TW, Jane_Doe, G1
Guidance on use
Every researcher should use this field to mark the claims that they have entered. Anytime a researcher modifies any data for an existing claim they should update this field so that any questions can be directed to the right person and the flow of work can be better tracked.
internal_comments:meta
Description
A field for temporary comments or notes for the researcher or research team working on the claim.
Attribute type
Text string
Status
This attribute is optional.
Key name
:meta/internal-comments
Example of use
Come back to this to determine date for claim
Guidance on use
Researchers may use this field to make temporary notes or leave temporary comments intended for others in the research team about a claim. These should eventually be addressed and the field cleared by the researcher or research team. If the claim needs an explanatory note or comment to be better understood, then that should be entered in the public_notes:meta field.
citation:refs:claim
Description
Field unique 32 character code assigned to citation(s) evidencing the location.
Attribute type
String in UUID format
Status
This attribute is optional.
Key name
:claim/citation:refs
Example of use
69dba35b-2b70-47cf-bfda-f80225f652c6, 4e99308c-f9c0-49e8-b97b-14c1e7bcb99d;bedf57b2-c20b-41e3-9dcf-b7b065eaa3b7
Guidance on use
Locations are drawn from an external gazeeter or geographic database, and because of this they do not require a citation. However, best practice is to include a citation whenever possible. When two or more citations are needed to evidence a location then a corresponding explanatory note should be entered in the public_notes:meta field. This field is for the Universally Unique Identifier (UUID) for each citation, found in the ref:source:access_point_id:admin field in the Sources sheet. When multiple citations are needed every UUID should be semi-colon separated.
id:entity
Description
A unique 36-character code assigned to each Location in the dataset.
Type of attribute
String in UUID format.
Status
This attribute is required.
Key name
:entity/id
Example of use
5f55f3f1-ed83-4766-b26a-fd11bedc398c
Guidance on use
This value is a Universally Unique Identifier (UUID) generated using a computer program. Every location has a UUID to distinguish it from any other location. This field is used in data entry for Incidents in incident:location:refs:assertion and positionings in positioning:location:refs:assertion.
location:humane_id:qa
Description
A human-readable unique identifier for each Location in the dataset.
Type of attribute
Text string.
Status
This attribute is optional.
Key name
:annotation/name
Example of use
Ta'izz Governorate (osm, poly) 5c35b342-0b5e-4648-86cd-7ad730d647fa
Guidance on use
The location:humane_id:qa should include other location fields that give a researcher a quick, human readable way to understand a location. Best practice is to include the name:annotation, origin:location, geo_type:qa and id:entity as this highlights the most important information while also creating a unique name due to the inclusion of id:entity. SFM adopts this approach with location:humane_id:qa with entries in the field following the below format:
Example
name:annotation (origin:location, geo_type:qa) id:entity
The value Ta'izz Governorate (osm, poly) 5c35b342-0b5e-4648-86cd-7ad730d647fa tells us that the name of the place is Ta'izz Governorate, that it is a Location found in osm (short for “OpenStreetMap”) that it denotes an area (poly); the UUID provides the hard link to a specific attribute in the Location table.
name:annotation
Description
The name of the Location as specified in the source of geospatial information from which it is taken.
Type of attribute
Text string.
Status
This attribute is required.
Key name
:annotation/name
Example of use
Ta'izz Governorate
Guidance on use
The value in name:annotation is to be taken directly from the geospatial data source. For example, if a Location is derived from OpenStreetMap, we take the value from OSM’s own “name” attribute and place it in name:annotation. Along with origin_id:location and geo_type:qa, name:annotation is needed for automation tools to identify the object within the geospatial data source. Where a Location is arbitrarily-defined, or is derived from a data source that does not provide a name, the Staff Researcher can provide one.
origin_id:location
Description
The identifier for the Location as specified in the source of geospatial information from which it is taken.
Type of attribute
String
Status
This attribute is required.
Key name
:location/origin-id
Example of use
383895
Guidance on use
The value in origin_id:location is to be taken directly from the geospatial data source. For example, if a Location is derived from OpenStreetMap, we take the value from OSM’s “id” attribute and place it in the origin_id:location attribute. Along with name:annotation and geo_type:qa, origin_id:location is needed in order for automation tools to identify the object within the geospatial data source. Where a Location is arbitrarily defined, or is derived from a data source that does not provide a ID number, the Staff Researcher can provide one.
geo_type:qa
Description
The two-dimensional geometric primitive of the Location, as defined in the source of geospatial information from which it is taken.
Type of attribute
Text
Status
This attribute is optional.
Key name
:location/geo-type
Example of use
point, poly, line
Guidance on use
This attribute used a controlled vocabulary to describe the type of geometry used to represent the Location on a map. The Staff Researcher can choose from the following three options:
point: the Location is a single distinct point on a map, represented by a single pair of geographic coordinates.
poly: the Location is a closed area on a map, its boundary described by a sequence of geographic coordinates.
line: the Location is a line on a map, described by a sequence of geographic coordinates. Alinemay also be closed.
The gazeteer used as the source of geometry may used different terminology to describe the Location. For example, in OpenStreetMap the boundaries of administrative areas (such as counties or states) are described using an object called a “relation”; although this can be a complex mix of different objects, for our purposes it is a poly because it describes an area.
origin:location
Description
The geospatial information source that provides information about this Location.
Type of attribute
String
Status
This attribute is required.
Key name
:location/origin
Example of use
osm, sfm, hdx, mimu, khrg
Guidance on use
The values in origin:location identify where automation tools should go to obtain spatial information about an object. For example, if the value osm is entered in origin:location this indicates that the automation tool should query OpenStreetMap in order to obtain spatial information about a Location. If osm were set, then the values in name:annotation and origin_id:location would correspond to the object name and ID number in OpenStreetMap. Locations can be derived from comprehensive online services, as well as other sources like locally-held .shp or .kml files. The number of origins is unlimited.
geometry:ref:entity
Description
The unique id generated by importer for the geojson for this Location.
Type of attribute
String
Status
This attribute is required.
Key name
:location/geo-feature:ref
Example of use
724f89db-98b3-5f5e-9947-7f50c049e5ea
Guidance on use
SFM’s location database gives a separate UUID for every geojson which must be matched to the location. This field enables the geographic data used to generate locations to be unique, and to connect these unique geojson to the data in the Locations sheet.
country:annotation
Description
Country in which the Location is situated.
Type of attribute
Text, controlled vocabulary
Status
This attribute is required.
Key name
:annotation/country
Example of use
ye, ng, mm
Guidance on use
Values for this attribute are the ISO 3166-1 alpha-2 country codes, which can be found (on the ISO website).
location:explicit_parent:annotation
Description
Manually entered location which contains the location.
Type of attribute
String
Status
This attribute is optional.
Key name
:annotation/location:explicit-parent
Example of use
Ilocos Norte (psa, poly) ceffdf36-f14b-410c-9fde-4c39f5a87c7c
Guidance on use
If a geographic dataset does not establish whether locations are within one another, this field may be used to manually create the hierarchy between locations. The location:humane_id:qa should be used in this field.
first_precise:range
Full guidance on rationale for and differences between precise and imprecise date ranges, the use of this attribute can be found in the Handbook page How Dates Work.
last_precise:range
Full guidance on rationale for and differences between precise and imprecise date ranges, the use of this attribute can be found in the Handbook page How Dates Work.
first_imprecise:range
Full guidance on rationale for and differences between precise and imprecise date ranges, the use of this attribute can be found in the Handbook page How Dates Work.
last_imprecise:range
Full guidance on rationale for and differences between precise and imprecise date ranges, the use of this attribute can be found in the Handbook page How Dates Work.
starting:range
Full guidance on rationale for and differences between precise and imprecise date ranges, the use of this attribute can be found in the Handbook page How Dates Work.
ending:range
Full guidance on rationale for and differences between precise and imprecise date ranges, the use of this attribute can be found in the Handbook page How Dates Work.
starting_context:range
Full guidance on rationale for and differences between precise and imprecise date ranges, the use of this attribute can be found in the Handbook page How Dates Work.
ending_context:range
Full guidance on rationale for and differences between precise and imprecise date ranges, the use of this attribute can be found in the Handbook page How Dates Work.
location:admin_level:qa
Description
The administrative level of the Location described in the attribute, if defined in the source of geographical information from which the Location is derived.
Type of attribute
String
Status
This attribute is optional.
Key name
n/a
Example of use
2
Guidance on use
In every country, places are organized hierarchically based on their administrative hierarchy. This feature passes into geographical information systems. At the top of the hierarchy rests the international boundary and capital city of a country; beneath this, there are sub-national divisions like states or provinces, with their respective capitals, followed by smaller and smaller administrative divisions districts, counties, municipalities, towns, suburbs, wards and so on. Different countries have different ways of describing these political and administrative divisions, but they are largely hierarchical and can be cross-compared. Knowing the level(s) at which a Location sits in the overall hierarchy provides us with a useful way to group and understand Locations.
The attribute location:admin_level:qa is drawn from the geographic source, or if the source lacks its own hierarchy then OpenStreetMap, which has a comprehensive table that matches the divisions that exist in every country.
The data in location:admin_level:qa and the other “admin_level” attributes can be automatically populated using a script that queries the OSM Overpass API.
location:admin_level_10:qa
Description
The administrative level 10 Location within which the present Location is wholly situated.
Type of attribute
String
Status
This attribute is optional.
Key name
n/a
Example of use
Byaw Taw Wa Ward (osm, poly) 119ce62f-0caa-4c0d-bb30-d02f58364814, a ward in Myanmar.
Guidance on use
This attribute contains the human-readable identifier (location:humane_id:qa) of the level 10 administrative area in which the current Location is situated. Level 10 is an extremely small administrative division and is rarely specified in freely available geospatial information sources.
location:admin_level_9:qa
Description
The administrative level 9 Location within which the present Location is wholly situated.
Type of attribute
String
Status
This attribute is optional.
Key name
n/a
Example of use
Zone 13 (osm, poly) b858ac31-9e46-4818-b70a-572756d60012, a barangay zone in the Philippines.
Guidance on use
This attribute contains the human-readable identifier (location:humane_id:qa) of the level 9 administrative area in which the current Location is situated. Level 9 is an extremely small administrative division and is rarely specified in freely available geospatial information sources.
location:admin_level_8:qa
Description
The administrative level 8 Location within which the present Location is wholly situated.
Type of attribute
String
Status
This attribute is optional.
Key name
n/a
Example of use
Ermita (osm, poly) 9989ba43-3b03-473a-8226-511a8eb82c3d, an administrative district of Manila in the Philippines.
Guidance on use
This attribute contains the human-readable identifier (location:humane_id:qa) of the level 8 administrative area in which the current Location is situated. Level 8 is a relatively small administrative division, and may not be commonly found in freely available geospatial information sources.
location:admin_level_7:qa
Description
The administrative level 7 Location within which the present Location is wholly situated.
Type of attribute
String
Status
This attribute is optional.
Key name
n/a
Example of use
Wuse II (osm, poly) 111f698a-421e-4fc8-9ace-c0aa62b461b5
Guidance on use
This attribute contains the human-readable identifier (location:humane_id:qa) of the level 7 administrative area in which the current Location is situated. Level 7 areas are commonly found in freely available geospatial information sources such as OpenStreetMap.
location:admin_level_6:qa
Description
The administrative level 6 Location within which the present Location is wholly situated.
Type of attribute
String
Status
This attribute is optional.
Key name
n/a
Example of use
Arbinda (osm, poly) 659c231e-eb1e-4c46-a710-b7663ef9f2e0, a commune rurale in Burkina Faso.
Guidance on use
This attribute contains the human-readable identifier (location:humane_id:qa) of the level 6 administrative area in which the current Location is situated. Level 6 areas are commonly found in freely available geospatial information sources such as OpenStreetMap.
location:admin_level_5:qa
Description
The administrative level 5 Location within which the present Location is wholly situated.
Type of attribute
String
Status
This attribute is optional.
Key name
n/a
Example of use
Seti (osm, poly) 64a4dd09-36d4-4455-bd07-a77addc91946, a zone in Nepal.
Guidance on use
This attribute contains the human-readable identifier (location:humane_id:qa) of the level 5 administrative area in which the current Location is situated. Level 5 areas are commonly found in freely available geospatial information sources such as OpenStreetMap.
location:admin_level_4:qa
Description
The administrative level 4 Location within which the present Location is wholly situated.
Type of attribute
String
Status
This attribute is optional.
Key name
n/a
Example of use
Gombe (osm, poly) 06791bb5-c39d-4a32-a05b-f3945c4f83ea, a state in Nigeria.
Guidance on use
This attribute contains the human-readable identifier (location:humane_id:qa) of the level 4 administrative area in which the current Location is situated. Level 4 areas are commonly found in freely available geospatial information sources such as OpenStreetMap, and are usually the largest sub-national administrative areas.
location:admin_level_3:qa
Description
The administrative level 3 Location within which the present Location is wholly situated.
Type of attribute
String
Status
This attribute is optional.
Key name
n/a
Example of use
Central Visayas (osm, poly) 81848978-3998-48bf-87a7-bd1888912aee, a region of the Philippines.
Guidance on use
This attribute contains the human-readable identifier (location:humane_id:qa) of the level 3 administrative area in which the current Location is situated. Where defined, level 3 administrative areas are commonly found in freely available geospatial information sources such as OpenStreetMap.
location:admin_level_2:qa
Description
The administrative level 2 location within which the present Location is wholly situated.
Type of attribute
String
Status
This attribute is optional.
Key name
n/a
Example of use
Mali (osm, poly) 8e7b492e-5346-4f43-91a0-55c1f3419468, Sudan (osm, poly) 7117df90-1e52-4726-806a-8e422a0511c6
Guidance on use
This attribute contains the human-readable identifier (location:humane_id:qa) of the level 2 administrative level, which for the OpenStreetMap schema is the international boundary of a country.
location:admin_level_1:qa
Description
The administrative level 1 Location within which the present Location is wholly situated.
Type of attribute
String
Status
This attribute is optional.
Key name
n/a
Example of use
Dodoma (ocha, poly) 8f9d115d-ef26-4d59-85a0-905cd9582adf
Guidance on use
This attribute contains the human-readable identifier (location:humane_id:qa) of the level 1 administrative level. The UN Office for the Coordination of Humanitarian Affairs (OCHA) defines the level 1 administrative level as the highest sub national boundaries of a country (OSM generally uses level 4 for these sub national boundaries).
location:admin_level_0:qa
Description
The administrative level 0 Location - the international state boundary for OCHA - within which the present Location is wholly situated.
Type of attribute
String
Status
This attribute is optional.
Key name
n/a
Example of use
United Republic of Tanzania (ocha, poly) 6f08e803-b1d8-4b8f-899a-1e20c4174441
Guidance on use
This attribute contains the human-readable identifier (location:humane_id:qa) of the international boundary of a country as defined in the UN Office for the Coordination of Humanitarian Affairs (OCHA) schema.
public_notes:meta
Description
Additional context or details about the claim for a public audience.
Attribute type
String
Status
This attribute is optional.
Key name
:meta/public-notes
Example of use
Citation @3c981094-fb7b-4b78-b8f6-b525a03f72b5, published on 15 July 2019, states that numerous military appointments occurred "last week". This is understood to mean the week starting the previous Sunday 7 July 2019 through Saturday 13 July 2019.
Guidance on use
This field should be used whenever any claim requires additional explanation because for a general reader the claim is not clearly and directly stated in the citation. For the example of use above a citation published on 15 July 2019 refers to something happening “last week” and as a result a researcher has determined the previous Sunday 7 July 2019 through Saturday 13 July 2019 should be entered into the appropriate fields of first_imprecise:range and last_imprecise:range. That range would not be immediately clear to a public audience since neither date is directly referenced in the text of the citation. As a result, the researcher should explain how that date range was evidenced by the citation.
type:entity
Description
Specifies the type of entity.
Attribute type
Text, controlled vocabulary.
Status
This field is required.
Key name
:entity/type
Example of use
claim
Guidance on use
For a location the only entry allowed for this field is location.