Data Stored in OpenStreetMap Layers

Since R2023b

OpenStreetMap^® files provide access to crowd-sourced map data from all over the world. The files store information about locations using tags. Each tag consists of a key and a value.

• The key provides context for the location. OpenStreetMap supports thousands of keys, such as highway, building, and address.

• The value provides detail about the key. Each key can support hundreds of values. For example, values for the highway key include "yes", "primary", "footway", and "cycleway".

When you read data from an OpenStreetMap file by using the readgeotable function, the function stores the data using a geospatial table. A geospatial table is a table or timetable object with a Shape variable and attribute variables.

The data that the readgeotable function reads depends on the value of the Layer name-value argument. This topic describes the data stored in each layer of an OpenStreetMap file.

Data Layers

Read data from an OpenStreetMap file by specifying the Layer name-value argument of the readgeotable function as "points", "lines", "multilinestrings", or "multipolygons". When you read data from an OpenStreetMap file, the geospatial table stores the tags using the attribute variables. For common tags, the names of the attribute variables match the keys.

Most locations stored in OpenStreetMap files do not have values for all the common tags. When a location does not contain a value for a tag, the geospatial table stores the value as "".

"points"

When you specify the Layer name-value argument as "points", the readgeotable function reads standalone node features from the file. The output geospatial table has these variables.

Variable	Description
Shape	Point shape, returned as a geopointshape object.
osm_id	OpenStreetMap ID, returned as a string scalar.
name	Primary name, returned as a string scalar.
barrier	Barrier, returned as a string scalar. The points layer includes barriers such as gates, toll booths, and border control points.
highway	Highway, returned as a string scalar. The points layer includes highway elements such as crosswalks, stop signs, and traffic signals.
ref	Reference number or code, returned as a string scalar.
address	Address, returned as a string scalar.
is_in	Descriptive location, returned as a string scalar. For example, this attribute can describe the city in which a point is located.
place	Type of place, returned as a string scalar. The points layer can label places as countries, states, or counties.
man_made	Man-made structure, returned as a string scalar. The points layer includes man-made structures such as windmills, antennas, and survey points.
other_tags	Other tags, returned as a string scalar. This variable stores the keys and values of OpenStreetMap tags that are not commonly used for points.
other_tags_dictionary	Other tags, returned as a cell array containing a dictionary. This variable stores the same content as other_tags in a more convenient form. For information on how to extract values stored in other_tags_dictionary, see the Read Data from OpenStreetMap Files example.

"lines"

When you specify the Layer name-value argument as "lines", the readgeotable function reads way features with no area from the file. The output geospatial table has these variables.

Variable	Description
Shape	Line shape, returned as a geolineshape object.
osm_id	OpenStreetMap ID, returned as a string scalar.
name	Primary name, returned as a string scalar.
highway	Highway, returned as a string scalar. The lines layer includes highway elements such as roads, footpaths, and cycleways.
waterway	Waterway, returned as a string scalar. The lines layer includes waterways such as rivers, drains, and dams.
aerialway	Aerialway, returned as a string scalar. The lines layer includes aerialways such as gondolas, chair lifts, and zip lines.
barrier	Barrier, returned as a string scalar. The lines layer includes barriers such as walls, fences, and guardrails.
man_made	Man-made structure, returned as a string scalar. The lines layer includes man-made structures such as pipelines, breakwaters, and embankments.
railway	Railway, returned as a string scalar. The lines layer includes railway elements such as subways and light rail routes.
other_tags	Other tags, returned as a string scalar. This variable stores the keys and values of OpenStreetMap tags that are not commonly used for lines.
other_tags_dictionary	Other tags, returned as a cell array containing a dictionary. This variable stores the same content as other_tags in a more convenient form. For information on how to extract values stored in other_tags_dictionary, see the Read Data from OpenStreetMap Files example.

"multilinestrings"

When you specify the Layer name-value argument as "multilinestrings", the readgeotable function reads relation features with a multilinestring or route type from the file. The output geospatial table has these variables.

Variable	Description
Shape	Line shape, returned as a geolineshape object.
osm_id	OpenStreetMap ID, returned as a string scalar.
name	Primary name, returned as a string scalar.
type	Type, returns as a string scalar.
other_tags	Other tags, returned as a string scalar. This variable stores the keys and values of OpenStreetMap tags that are not commonly used for multilinestrings.
other_tags_dictionary	Other tags, returned as a cell array containing a dictionary. This variable stores the same content as other_tags in a more convenient form. For information on how to extract values stored in other_tags_dictionary, see the Read Data from OpenStreetMap Files example.

"multipolygons"

When you specify the Layer name-value argument as "multipolygons", the readgeotable function reads way features with area, and relationship features with a multipolygon or boundary type, from the file. The output geospatial table has these variables.

Variable	Description
Shape	Polygon shape, returned as a geopolyshape object.
osm_id	OpenStreetMap ID, returned as a string scalar.
osm_way_id	OpenStreetMap way ID, returned as a string scalar.
name	Primary name, returned as a string scalar.
type	Type, returns as a string scalar.
aeroway	Aeroway, returned as a string scalar. The multipolygons layer includes aeroway elements such as runways, airport terminals, and control towers.
amenity	Amenity, returned as a string scalar. The multipolygons layer includes amenities such as libraries, restaurants, and hospitals.
admin_level	Administrative level within a government hierarchy, returned as a string scalar.
barrier	Barrier, returned as a string scalar. The multipolygons layer includes barriers such as walls and toll booths.
boundary	Boundary, returned as a string scalar. The multipolygons layer includes boundaries such as administrative boundaries, political boundaries, and national park boundaries.
building	Building, returned as a string scalar. The multipolygons layer includes buildings such as houses, commercial buildings, and retail shops.
craft	Workplace for creating craft goods, returned as a string scalar. The multipolygons layer includes workplaces for occupations such as electrician, shoemaker, and baker.
geological	Geological feature, returned as a string scalar. The multipolygons layer includes geological features such as lava fields and craters.
historic	Historic site, returned as a string scalar. The multipolygons layer includes historic sites such as buildings, farms, and battlefields.
land_area	Administrative boundary, returned as a string scalar.
landuse	Primary use of the land, returned as a string scalar. The multipolygons layer includes primary land uses such as education, industry, residence, and retail.
leisure	Location for leisure activity, returned as a string scalar. The multipolygons layer includes locations such as dog parks, ice rinks, and sports arenas.
man_made	Man-made structure, returned as a string scalar. The multipolygons layer includes man-made structures such as bridges, courtyards, and satellite dishes.
military	Building or land used by the military, returned as a string scalar. The multipolygons layer includes military features such as bunkers and academies.
natural	Natural land feature, returned as a string scalar. The multipolygons layer includes natural land features such as grasslands, bays, and sinkholes.
office	Business office, returned as a string scalar. The multipolygons layer includes offices such as financial offices, government offices, and telecommunication offices.
place	Type of place, returned as a string scalar. The multipolygons layer includes place values such as state, region, and province.
shop	Shop, returned as a string scalar. The multipolygons layer includes shops such as bakeries, shopping malls, and car repair shops.
sport	Location for playing a sport, returned as a string scalar. The multipolygons layer includes sport locations such as baseball fields, rock climbing gyms, and weightlifting gyms.
tourism	Location of interest to tourists, returned as a string scalar. The multipolygons layer includes tourist locations such as campsites, theme parks, and art galleries.
other_tags	Other tags, returned as a string scalar. This variable stores the keys and values of OpenStreetMap tags that are not commonly used for points.
other_tags_dictionary	Other tags, returned as a cell array containing a dictionary. This variable stores the same content as other_tags in a more convenient form. For information on how to extract the values stored in other_tags_dictionary, see the Read Data from OpenStreetMap Files example.

Building Layers

Read buildings from an OpenStreetMap file by specifying the Layer name-value argument of the readgeotable function as "buildings" or "buildingparts". When you read buildings from an OpenStreetMap file, the geospatial table stores data that MATLAB^® derives from the tags.

"buildings"

When you specify the Layer name-value argument as "buildings", the output geospatial table has these variables.

Variable	Description
Shape	Building footprint, returned as a geopolyshape object.
Centroid	Centroid of the building footprint, returned as a geopointshape object.
Type	Type, returned as a map.Buildings.Type enumeration with one of these values: standard — Standard building that consists of one part with a flat roof. composite — Composite building that consists of multiple parts. The table stores the parts in the Parts variable. roof — Roof. The table stores the roof shape in the RoofShape variable and the roof direction in the RoofDirection variable.
Parts	Parts, returned as a one-element cell array containing a geospatial table. The geospatial table has the same variable names as the "buildings" layer.
ID	OpenStreetMap ID, returned as a string scalar.
MinHeight	Minimum height, returned as a scalar of type double in units of meters above ground.
MaxHeight	Maximum height, returned as a scalar of type double in units of meters above ground.
Name	Name, returned as a string scalar.
Material	Material, returned as a string scalar.
Color	Color, returned as a string scalar that represents a hexadecimal color code. A hexadecimal color code starts with a hash symbol (#) followed by three or six hexadecimal digits.
RoofShape	Roof shape, returned as a string scalar. This variable has a value only when the Type variable has a value of "roof". Supported roof shapes include "gabled", "flat", "hipped", and "pyramidal".
RoofDirection	Roof direction, returned as a string scalar. This variable has a value only when the Type variable has a value of "roof". Supported roof directions include: A compass direction, for example "NW" or "northwest". A number, in degrees, in the range [0, 360], for example "180". The direction of the roof ridge with respect to the longest building edge, for example "along" or "across".

"buildingparts"

The "buildingparts" layer is a flattened version of the "buildings" layer. While the "buildings" layer stores building parts using the Parts variable, the "buildingparts" layer stores building parts using separate table rows.

When you specify the Layer name-value argument of the readgeotable function as "buildingparts", the output geospatial table has these variables.

Variable	Description
Shape	Footprint of the building part, returned as a geopolyshape object.
Centroid	Centroid of the building part footprint, returned as a geopointshape object.
Type	Type, returned as a map.Buildings.Type enumeration with one of these values: standard — Standard building that consists of one part with a flat roof. composite — Composite building that consists of multiple parts. roof — Roof. The table stores the roof shape in the RoofShape variable and the roof direction in the RoofDirection variable.
BuildingID	OpenStreetMap ID of the building, returned as a string scalar.
PartID	OpenStreetMap ID of the building part, returned as a string scalar.
MinHeight	Minimum height, returned as a scalar of type double in units of meters above ground.
MaxHeight	Maximum height, returned as a scalar of type double in units of meters above ground.
Name	Name, returned as a string scalar.
Material	Material, returned as a string scalar.
Color	Color, returned as a string scalar that represents a hexadecimal color code. A hexadecimal color code starts with a hash symbol (#) followed by three or six hexadecimal digits.
RoofShape	Roof shape, returned as a string scalar. This variable has a value only when the Type variable has a value of "roof". Supported roof shapes include "gabled", "flat", "hipped", and "pyramidal".
RoofDirection	Roof direction, returned as a string scalar. This variable has a value only when the Type variable has a value of "roof". Supported roof directions include: A compass direction, for example "NW" or "northwest". A number, in degrees, in the range [0,360], for example "180". The direction of the roof ridge with respect to the longest building edge, for example "along" or "across".