readgeotable

Read geospatial table from vector data file

Since R2021b

Syntax

T = readgeotable(filename)

T = readgeotable(filename,Name=Value)

Description

T = readgeotable(filename) creates a geospatial table by reading geographic or projected vector data from a file with a format such as shapefile, KML, or Esri file geodatabase. For a full list of supported formats, see Supported Formats.

T = readgeotable(filename,Name=Value) specifies options using name-value arguments. For example, specify the coordinate system type using the CoordinateSystemType name-value argument.

Examples

Read Shapefile as Geospatial Table

Read a shapefile, containing a network of roads in Concord, MA, into the workspace as a geospatial table.

T = readgeotable("concord_roads.shp");

The Shape variable of the table contains information about the road shapes, including the coordinate reference system (CRS). The road shapes in this shapefile use a projected CRS.

T.Shape.ProjectedCRS

ans = 
  projcrs with properties:

                    Name: "NAD83 / Massachusetts Mainland"
           GeographicCRS: [1×1 geocrs]
        ProjectionMethod: "Lambert Conic Conformal (2SP)"
              LengthUnit: "meter"
    ProjectionParameters: [1×1 map.crs.ProjectionParameters]

Display the roads on a map.

mapshow(T)
xlabel("x (meters)")
ylabel("y (meters)")

Read Shapefile with No Projection File

An optional projection file (.prj) determines the coordinate system type for a shapefile. When your shapefile does not have a projection file, but you know the coordinate system type, you can specify it by using the CoordinateSystemType name-value argument.

Read a shapefile called tsunamis.shp, containing information about tsunami events, into the workspace. The metadata accompanying the file indicates that the shapefile uses geographic coordinates.

T = readgeotable("tsunamis.shp",CoordinateSystemType="geographic");

View the Shape variable of the geospatial table. The tsunami source locations are stored as points.

T.Shape

ans = 
  162×1 geopointshape array with properties:

               NumPoints: [162×1 double]
                Latitude: [162×1 double]
               Longitude: [162×1 double]
                Geometry: "point"
    CoordinateSystemType: "geographic"
           GeographicCRS: []

Plot the source locations on a map.

lat = T.Shape.Latitude;
lon = T.Shape.Longitude;
geoiconchart(lat,lon)

Read Layers from GPX Files

GPX files can contain up to five layers: waypoints, tracks, track points, routes, and route points. When you read a layer containing track points or route points, the geospatial table contains an ID variable that associates the points with a track or route.

Import the tracks layer of a GPX file with two tracks. The Shape variable for each track is a geolineshape object.

T = readgeotable("sample_tracks.gpx",Layer="tracks")

T=2×3 table
       Shape                                                  Name                                               Number
    ____________    _________________________________________________________________________________________    ______

    geolineshape    "Track logs from walking the perimeter of the MathWorks campus in Natick on May 21, 2007"      1   
    geolineshape    "Track logs from biking from Concord to the MathWorks campus in Natick on June 30, 2011"       2   

View the shape of each track. The first track has one segment and the second track has five segments.

T.Shape(1)

ans = 
  geolineshape with properties:

                NumParts: 1
                Geometry: "line"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

T.Shape(2)

ans = 
  geolineshape with properties:

                NumParts: 5
                Geometry: "line"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Import the track points layer. The Shape variable for each point is a geopointshape object.

T2 = readgeotable("sample_tracks.gpx",Layer="track_points");
T2.Shape

ans = 
  2586×1 geopointshape array with properties:

               NumPoints: [2586×1 double]
                Latitude: [2586×1 double]
               Longitude: [2586×1 double]
                Geometry: "point"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Create a subtable that contains points in the second track only. For this file, points in the second track have a TrackFID value of 1.

rows = (T2.TrackFID == 1);
T3 = T2(rows,:);

Display the points in the subtable using a blue line.

lat = T3.Shape.Latitude;
lon = T3.Shape.Longitude;
geoplot(lat,lon,Color="b")

Read GeoJSON File from Web Service

Read GeoJSON data from a website and save it in the file storms.geojson. The data contains day 1 convective outlooks from the NOAA/NWS Storm Prediction Center. For more information about convective outlooks, see [1]. For links to the data, see [2].

websave("storms.geojson","https://www.spc.noaa.gov/products/outlook/day1otlk_cat.lyr.geojson");

Read the data into a geospatial table. If the file contains no data for the readgeotable function to read, such as when there are no severe thunderstorm threats, create a geospatial table with an empty polygon shape instead.

try
    GT = readgeotable("storms.geojson");
catch
    GT = table(geopolyshape,"No Data","none",VariableNames=["Shape" "LABEL2" "fill"]);
end

View the Shape variable of the geospatial table. The table stores the geographic areas as polygons.

GT.Shape

ans=2×1 geopolyshape array with properties:
              NumRegions: [2×1 double]
                NumHoles: [2×1 double]
                Geometry: "polygon"
    CoordinateSystemType: "geographic"
           GeographicCRS: [1×1 geocrs]

Day 1 convective outlooks change from day to day, so your results can be different.

Display the convective outlooks over a satellite basemap. To create a legend from the thunderstorm risk categories, plot each row of the table as a separate polygon.

figure
geobasemap satellite
hold on
for k = 1:height(GT)
    row = GT(k,:);
    geoplot(row,"DisplayName",row.LABEL2,"FaceColor",row.fill)
end
legend
alpha(0.6)

Add a title, including the access date.

dt = datetime("today",Format="MMMM d, yyyy");
title("Day 1 Convective Outlooks",string(dt))

[1] "SPC Products." NOAA/National Weather Service Storm Prediction Center. Accessed June 28, 2022. https://www.spc.noaa.gov/misc/about.html.

[2] "SPC Shapefile/KML/KMZ Links." NOAA/National Weather Service Storm Prediction Center. Accessed June 28, 2022. https://www.spc.noaa.gov/gis/.

Read Data Layers from OpenStreetMap File

Since R2023b

OpenStreetMap® files contain several data layers, including point, line, multilinestring, and multipolygon layers. The data that the readgeotable function reads from an OpenStreetMap file depends on the layer that you specify.

Specify the name of an OpenStreetMap file [1] containing data for several city blocks in Shibuya, Tokyo, Japan.

filename = "shibuya.osm";

Read the lines layer into a geospatial table. The lines layer represents features such as roads, sidewalks, and railroad tracks. The table represents the lines using line shapes in geographic coordinates.

linesLayer = readgeotable(filename,Layer="lines");

Display the lines on a map.

figure
geoplot(linesLayer)
title("Lines Layer")

Read the points layer into a geospatial table. The points layer represents features such as traffic signals, bus stops, and subway entrances. The table represents the points using point shapes in geographic coordinates.

pointsLayer = readgeotable(filename,Layer="points");

Display the points on the same map.

hold on
geoplot(pointsLayer)
title("Points and Lines Layers")

For information on how to read specific geographic features, such as railways and subway entrances, see the Read Data from OpenStreetMap Files example.

[1] You can download OpenStreetMap files from https://www.openstreetmap.org, which provides access to crowd-sourced map data all over the world. The data is licensed under the Open Data Commons Open Database License (ODbL), https://opendatacommons.org/licenses/odbl/.

Read Buildings Layer from OpenStreetMap File

Since R2023b

Read buildings data, such as footprints, centroids, and heights, from OpenStreetMap files with the .osm extension.

Specify the name of an OpenStreetMap file [1] containing data for several city blocks in Shibuya, Tokyo, Japan.

filename = "shibuya.osm";

Read the buildings layer into a geospatial table by specifying the Layer name-value argument of the readgeotable function as "buildings". The table represents the buildings using polygon shapes in geographic coordinates.

buildingsLayer = readgeotable(filename,Layer="buildings");

Display the buildings on a map, and apply color using the maximum heights of the buildings. Add a title, change the colormap, and add a labeled color bar.

figure
geoplot(buildingsLayer,ColorVariable="MaxHeight")

title("Maximum Heights of Buildings")
colormap sky
c = colorbar;
c.Label.String = "Height in Meters";

For information on how to display buildings data based on information stored in the geospatial table, see the Display Buildings from OpenStreetMap Files example.

[1] You can download OpenStreetMap files from https://www.openstreetmap.org, which provides access to crowd-sourced map data all over the world. The data is licensed under the Open Data Commons Open Database License (ODbL), https://opendatacommons.org/licenses/odbl/.

Input Arguments

filename — Name of file to read

character vector | string scalar

Name of the file to read, specified as a character vector or string scalar. The form of filename depends on the location of your file.

• If the file is in your current folder or in a folder on the MATLAB^® path, then specify the name of the file, such as "myFile.shp".

• If the file is not in the current folder or in a folder on the MATLAB path, then specify the full or relative path name, such as "C:\myfolder\myFile.gpx" or "dataDir\myFile.kml".

For a list of supported file formats, see Supported Formats.

To read an Esri file geodatabase, you must either specify the full or relative path name or include the geodatabase in your current folder.

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: readgeotable("sample_tracks.gpx",Layer="track_points") reads the track points layer from the GPX file.

Layer — Layer to read

positive integer | string scalar | character vector

Layer to read when the file contains multiple layers, specified as a positive integer, a string scalar, or a character vector. If you specify an integer, then it must be less than or equal to the number of vector layers in the file. This argument is case-sensitive.

The layers contained in a file depend on the file format.

File Format	Layer Format
Esri file geodatabase	The content of the file determines the number of layers and the names of the layers.
GeoJSON	The content of the file determines the number of layers and the names of the layers.
GeoPackage	The content of the file determines the number of layers and the names of the layers.
GPX	Specify the layer as one of these options: "waypoints" — Waypoints. "tracks" — Track lines. "track_points" — Track points. When you read track points, the geospatial table contains an ID variable, TrackFID, that associates each point with a track. "routes" — Route lines. "route_points" — Route points. When you read route points, the geospatial table contains an ID variable, RouteFID, that associates each point with a route.
KML	Each folder and subfolder corresponds to a layer, and the folder names match the layer names.
KMZ	Each folder and subfolder in the underlying KML file corresponds to a layer, and the folder names match the layer names.
OpenStreetMap®	Specify the layer as one of these options. For more information about the data stored in each layer, see Data Stored in OpenStreetMap Layers. "points" — Points. "lines" — Lines. "multilinestrings" — Multilinestrings. "multipolygons" — Multipolygons. "buildings" — Buildings. This layer requires the file to have the .osm extension. "buildingparts" — Building parts. Use this layer when you want to customize the buildings stored in the file. This layer requires the file to have the .osm extension.
Shapefile	Shapefiles have one layer.

Data Types: single | double | char | string

CoordinateSystemType — Coordinate system type

"auto" (default) | "geographic" | "planar"

Coordinate system type, specified as one of these values:

• "auto" — Create the Shape table variable based on the contents of the file.

• "geographic" — Create the Shape table variable using geopointshape, geolineshape, and geopolyshape objects.

• "planar" — Create the Shape table variable using mappointshape, maplineshape, and mappolyshape objects.

Specify the coordinate system type when the readgeotable function is unable to detect the coordinate system type.

For shapefiles, the coordinate system type is determined by an optional projection file (.prj). If your shapefile does not have a projection file, you can try to determine the coordinate system type using one of these options:

• Refer to the metadata.

• Ask your data provider.

• Return information about the shapefile as a structure by using the shapeinfo function. Then, view the limits of the data by querying the BoundingBox field of the structure. The limits might help you predict the coordinate system type.

VariableNamingRule — Flag to preserve variable names

"preserve" (default) | "modify"

Flag to preserve variable names, specified as one of these options:

• "preserve" — Preserve variable names that are not valid MATLAB identifiers, such as variable names that include spaces and non-ASCII characters.

• "modify" — Convert invalid variable names, as identified by the isvarname function, to valid MATLAB identifiers.

Data Types: char | string

Output Arguments

T — Geospatial table

geospatial table

Geospatial table, returned as a geospatial table. A geospatial table is a table object with a Shape variable and attribute variables.

• The Shape variable contains 2-D information about point, line, and polygon shapes. The Shape variable can contain combinations of shape types. All the shapes have the same coordinate reference system (CRS).

  The readgeotable function represents shapes with coordinates in geographic CRSs by using geopointshape, geolineshape, and geopolyshape objects.

  The readgeotable function represents shapes with coordinates in projected CRSs by using mappointshape, maplineshape, and mappolyshape objects.

• The attribute variables contain data such as names, classifications, and measurements.

When the data file contains CRS information, the readgeotable function stores the information as a projcrs or geocrs object within each shape object.

For more information about geospatial tables created from OpenStreetMap files, see Data Stored in OpenStreetMap Layers.

More About

Supported Formats

The readgeotable function supports these file formats.

• Esri file geodatabase (.gdb)

• GeoJSON (.json or .geojson)

• GeoPackage (.gpkg) (since R2025a)

• GPX (.gpx)

• KML (.kml)

• KMZ (.kmz) (since R2023b)

• OpenStreetMap (.osm or .osm.pbf) (since R2023b)

• Shapefile (.shp)

Some file formats consist of a main file and multiple supporting files. For example, shapefiles include a main file (.shp), an index file (.shx), and an attribute file (.dbf). When you read a data file with supporting files using the readgeotable function, specify the extension of the main file.

When the file contains 3-D points, lines, or polygons, the function reads only the 2-D information into the Shape variable of the geospatial table.

For GeoJSON files, all attributes apply to all rows in the geospatial table, even when the GeoJSON file does not apply an attribute to all elements. When the file does not apply an attribute to an element, the corresponding cell in the geospatial table contains a missing data value.

For GPX files, Garmin® extensions are not supported.

For KML and KMZ files, the readgeotable function reads only shapes, names, and descriptions into the geospatial table.

Version History

Introduced in R2021b

R2025a: Read vector data from GeoPackage files

The readgeotable function can read vector data from files in the GeoPackage format (.gpkg).

R2023b: Read data and buildings from OpenStreetMap files

The readgeotable function can read data and buildings from files in OpenStreetMap format (.osm, .osm.pbf).

R2023b: Read data from KMZ files

The readgeotable function can read data from files in KMZ format (.kmz).