geocode

Get shape object from geocoded placename

Since R2024b

collapse all in page

Syntax

geocodedGT = geocode(names)

geocodedGT = geocode(names,adminlevel)

geocodedGT = geocode(names,customNamesGT)

geocodedGT = geocode(names,customNamesGT,namevar)

geocodedGT = geocode(___,Name=Value)

Description

Use Installed List of Placenames

geocodedGT = geocode(names) geocodes the specified placenames by converting the placenames into shape objects that are associated with the placenames. The output is a geospatial table that contains the placenames and the shape objects. For more information about geocoding, see Geocoding.

By default, the function finds matches for the specified placenames by searching an installed list of world regions, US states, and world cities. To view the placenames in the installed list, use the placenames function.

example

geocodedGT = geocode(names,adminlevel) specifies the administration level for the placenames.

example

Use Custom List of Placenames

geocodedGT = geocode(names,customNamesGT) uses a custom table of placenames and shape objects instead of the installed list of placenames. This syntax searches for the placenames using the case-insensitive name table variable. If the table does not have a name table variable, then the function searches the second table variable.

example

geocodedGT = geocode(names,customNamesGT,namevar) specifies the table variable that contains the custom placenames.

example

Additional Options

geocodedGT = geocode(___,Name=Value) specifies options using one or more name-value arguments, in addition to any combination of input arguments from the previous syntaxes. For example, specify whether to ignore case by using the IgnoreCase name-value argument.

Examples

collapse all

Geocode World Regions

Open Live Script

Geocode the world region of Europe. The output is a geospatial table that contains the placename and a shape object associated with the placename.

geocodedGT = geocode("Europe")

geocodedGT=1×2 table
       Shape          Name  
    ____________    ________

    geopolyshape    "Europe"

When you geocode the name of a world region, the shape object is an area of interest (AOI) that depicts either a bounding box or an outline of the region. Display the boundary of the AOI on a map.

figure
geobasemap satellite
geoplot(geocodedGT,FaceColor="none",LineWidth=1.5,EdgeColor="w")

Figure contains an axes object with type geoaxes. The geoaxes object contains an object of type polygon.

Geocode US States

Open Live Script

Specify placenames for the states that comprise New England: Maine, New Hampshire, Vermont, Massachusetts, Connecticut, and Rhode Island. Then, geocode the placenames. The output is a geospatial table that contains the placenames and the shape objects associated with the placenames.

names = ["Maine","New Hampshire","Vermont","Massachusetts","Connecticut","Rhode Island"];
geocodedGT = geocode(names,"state")

geocodedGT=6×2 table
       Shape             Name      
    ____________    _______________

    geopolyshape    "Maine"        
    geopolyshape    "New Hampshire"
    geopolyshape    "Vermont"      
    geopolyshape    "Massachusetts"
    geopolyshape    "Connecticut"  
    geopolyshape    "Rhode Island"

When you geocode the names of US states, the shape objects are AOIs that depict the outlines of the states. Display the AOIs on a map.

figure
geobasemap none
geoplot(geocodedGT)

Figure contains an axes object with type geoaxes. The geoaxes object contains an object of type polygon.

Geocode World Cities

Open Live Script

Geocode all the world cities in the installed list of placenames. Then, clip the cities to an AOI.

Get the names of the world cities by using the placenames function.

names = placenames("city");

Geocode the placenames and view the first eight rows of the output table. When you geocode the names of world cities, the shape objects in the output table are points that depict the city locations.

geocodedGT = geocode(names,"city");
head(geocodedGT)

             Shape                 Name     
    _______________________    _____________

    ( 5.2985°N,   3.9509°W)    "Abidjan"    
    (24.6525°N,  54.7589°E)    "Abu Dhabi"  
    ( 5.6106°N,   0.2121°W)    "Accra"      
    (37.0613°N,  35.3894°E)    "Adana"      
    ( 9.0235°N,  38.7575°E)    "Addis Ababa"
    (34.6645°S, 138.8528°E)    "Adelaide"   
    (12.8767°N,  44.5408°E)    "Aden"       
    (22.7778°N,  72.2474°E)    "Ahmadabad"

Prepare to clip the world cities by extracting the points from the table.

points = geocodedGT.Shape;

Get an AOI that depicts a bounding box for South America. Then, clip the world cities to the AOI. For more information about clipping shapes to AOIs, see Clip Vector Data to Area of Interest.

GT = geocode("South America");
aoi = GT.Shape;

clipped = geoclip(points,aoi);

Display the AOI and the clipped cities on a map.

figure
geoplot(aoi,FaceColor="none")
hold on
geoplot(clipped)

Figure contains an axes object with type geoaxes. The geoaxes object contains 2 objects of type polygon, point.

Geocode Custom Placenames

Open Live Script

Create a custom table of placenames by reading data from a file. Then, use the custom table to geocode a specified placename.

Create the custom table by reading data from a shapefile that contains placenames in Boston. The table stores the placenames in the NAME variable and the locations of the placenames in the Shape variable.

customNamesGT = readgeotable("boston_placenames.shp")

customNamesGT=13×4 table
            Shape                     NAME               FEATURE             COORD      
    ______________________    ____________________    _____________    _________________

    (234028.23, 900038.00)    "'BACK BAY'"            "PPL-SUBDVSN"    "422100N0710515W"
    (233569.77, 900190.06)    "BACK BAY FENS"         "MARSH"          "422105N0710535W"
    (235739.28, 901126.44)    "BEACON HILL"           "HILL"           "422135N0710400W"
    (236266.39, 900974.88)    "BOSTON"                "PPL"            "422130N0710337W"
    (235743.22, 900355.06)    "BOSTON NECK"           "PENINSULA"      "422110N0710400W"
    (234685.09, 901429.69)    "BROAD CANAL"           "CANAL"          "422145N0710446W"
    (232989.64, 901884.31)    "CAMBRIDGE"             "PPL"            "422200N0710600W"
    (236536.17, 901901.88)    "COPPS HILL"            "HILL"           "422200N0710325W"
    (234591.28, 901892.00)    "'EAST CAMBRIDGE'"      "PPL-SUBDVSN"    "422200N0710450W"
    (235741.66, 900663.62)    "FLAGSTAFF HILL"        "HILL"           "422120N0710400W"
    (237114.73, 900670.75)    "FORT POINT CHANNEL"    "CHANNEL"        "422120N0710300W"
    (235741.31, 900725.31)    "FROG POND"             "LAKE"           "422122N0710400W"
    (236548.23, 899587.88)    "SOUTH BAY"             "INLET"          "422045N0710325W"

Specify the placenames of two hills in Boston. Then, geocode the placenames by searching the custom table. By default, the geocode function searches for the placenames using the NAME variable of the custom table.

names = ["BEACON HILL","COPPS HILL"];
geocodedGT = geocode(names,customNamesGT);

View the output table. When you pass a custom table of placenames to the geocode function, the output table is a subset of the input table.

geocodedGT

geocodedGT=2×4 table
            Shape                 NAME         FEATURE          COORD      
    ______________________    _____________    _______    _________________

    (235739.28, 901126.44)    "BEACON HILL"    "HILL"     "422135N0710400W"
    (236536.17, 901901.88)    "COPPS HILL"     "HILL"     "422200N0710325W"

Geocode Custom Placenames Using Specified Table Variable

Open Live Script

Create a custom table of placenames by reading data from a file. Then, geocode a specified placename by searching the specified table variable of placenames.

Create the custom table by reading data from a shapefile that contains tsunami events. The table stores the placenames in the Location variable and the shape objects in the Shape variable.

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

             Shape             Year    Month    Day    Hour    Minute    Second    Val_Code           Validity            Cause_Code         Cause          Eq_Mag         Country                 Location            Max_Height    Iida_Mag    Intensity    Num_Deaths    Desc_Deaths
    _______________________    ____    _____    ___    ____    ______    ______    ________    _______________________    __________    ________________    ______    _________________    ________________________    __________    ________    _________    __________    ___________

    ( 3.8000°S, 128.3000°E)    1950     10       8       3       23       NaN         2        "questionable tsunami"         1         "Earthquake"         7.6      "INDONESIA"          "JAVA TRENCH, INDONESIA"        2.8         1.5          1.5             0            0     
    (19.5000°N, 156.0000°W)    1951      8      21      10       57       NaN         4        "definite tsunami"             1         "Earthquake"         6.9      "USA"                "HAWAII"                        3.6         1.8          NaN             0            0     
    ( 9.0200°S, 157.9500°E)    1951     12      22       0        0       NaN         2        "questionable tsunami"         6         "Volcano"            NaN      "SOLOMON ISLANDS"    "KAVACHI"                         6         2.6          NaN             0            0     
    (42.1500°N, 143.8500°E)    1952      3       4       1       22        41         4        "definite tsunami"             1         "Earthquake"         8.1      "JAPAN"              "SE. HOKKAIDO ISLAND"           6.5         2.7            2            33            1     
    (19.1000°N, 155.0000°W)    1952      3      17       3       58       NaN         4        "definite tsunami"             1         "Earthquake"         4.5      "USA"                "HAWAII"                          1         NaN          NaN             0            0     
    (43.1000°N,  82.4000°W)    1952      5       6       0        0       NaN         1        "very doubtful tsunami"        9         "Meteorological"     NaN      "USA"                "LAKE HURON, MI"               1.52         NaN          NaN             0            0     
    (52.7500°N, 159.5000°E)    1952     11       4      16       58       NaN         4        "definite tsunami"             1         "Earthquake"           9      "RUSSIA"             "KAMCHATKA"                      18         4.2            4          2236            3     
    (50.0000°N, 156.5000°E)    1953      3      18       0        0       NaN         3        "probable tsunami"             1         "Earthquake"         5.8      "RUSSIA"             "N. KURIL ISLANDS"              1.5         0.6          NaN             0            0

Geocode the placename Hawaii by searching the custom table. Specify the table variable containing the placenames as Location.

name = "Hawaii";
geocodedGT = geocode(name,customNamesGT,"Location");

View the output table. When you pass a custom table of placenames to the geocode function, the output table is a subset of the input table.

geocodedGT

geocodedGT=3×19 table
             Shape             Year    Month    Day    Hour    Minute    Second    Val_Code         Validity         Cause_Code              Cause               Eq_Mag    Country    Location    Max_Height    Iida_Mag    Intensity    Num_Deaths    Desc_Deaths
    _______________________    ____    _____    ___    ____    ______    ______    ________    __________________    __________    __________________________    ______    _______    ________    __________    ________    _________    __________    ___________

    (19.5000°N, 156.0000°W)    1951      8      21      10       57        NaN        4        "definite tsunami"        1         "Earthquake"                   6.9       "USA"     "HAWAII"        3.6         1.8          NaN           0              0     
    (19.1000°N, 155.0000°W)    1952      3      17       3       58        NaN        4        "definite tsunami"        1         "Earthquake"                   4.5       "USA"     "HAWAII"          1         NaN          NaN           0              0     
    (19.3340°N, 155.0240°W)    1975     11      29      14       47       40.4        4        "definite tsunami"        3         "Earthquake and Landslide"     7.1       "USA"     "HAWAII"       14.3           3            3           2              1

Input Arguments

collapse all

`names` — Placenames
string scalar | vector of strings | character vector | cell array of character vectors

Placenames, specified as a string scalar, a vector of strings, a character vector, or a cell array of character vectors.

By default, the function searches an installed list of placenames. To view the installed list of placenames, use the placenames function.

`adminlevel` — Administration level
`"region"` | `"state"` | `"city"`

Administration level, specified as one of these options:

"region" — World regions
"state" — US states and the District of Columbia
"city" — World cities

To view the installed list of placenames for each administration level, use the placenames function.

`customNamesGT` — Custom placenames and shapes
geospatial table

Custom placenames and shapes, specified as a geospatial table. For more information about geospatial tables, see Create Geospatial Tables.

customNamesGT must contain these table variables:

A Shape variable that specifies the point, line, or polygon shapes.
A variable that specifies the custom placenames. This variable must contain text data.

By default, the function searches for the specified placenames using the case-insensitive name table variable. If the table does not have a name variable, or has more than one name variable, then the function uses the second table variable. You can specify which table variable to search by using the namevar argument.

`namevar` — Table variable containing custom placenames
string scalar | character vector | `pattern` object | numeric scalar | logical vector | `vartype()`

Table variable containing the custom placenames, specified using one of these indexing schemes. The table variable must contain text data.

Indexing Scheme Examples

Indexing Scheme	Examples
Variable name: A string scalar or character vector. A `pattern` object. The pattern object must refer to only one variable.	`"A"` or `'A'` — A variable named `A` `"Var"+digitsPattern(1)` — The variable with the name `"Var"` followed by a single digit
Variable index: An index number that refers to the location of a variable in the table. A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing `0` or `false` values.	`3` — The third variable from the table `[false false true]` — The third variable
Variable type: A `vartype` subscript that selects a table variable of a specified type. The subscript must refer to only one variable.	`vartype("double")` — The variable containing double values

Variable name:

A string scalar or character vector.
A pattern object. The pattern object must refer to only one variable.

"A" or 'A' — A variable named A
"Var"+digitsPattern(1) — The variable with the name "Var" followed by a single digit

Variable index:

An index number that refers to the location of a variable in the table.
A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 or false values.

3 — The third variable from the table
[false false true] — The third variable

Variable type:

A vartype subscript that selects a table variable of a specified type. The subscript must refer to only one variable.

vartype("double") — The variable containing double values

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: geocode(names,IgnoreCase=false) does not ignore case when comparing names to the list of placenames.

`PartialMatch` — Use partial string matching
`true` or `1` (default) | `false` or `0`

Use partial string matching, specified as a numeric or logical 1 (true) or 0 (false).

true — Use partial string matching when comparing names to the list of placenames. This option supports partial matching of leading characters.
false — Do not use partial string matching when comparing names to the list of placenames.

`IgnoreCase` — Ignore case
`true` or `1` (default) | `false` or `0`

Ignore case, specified as a numeric or logical 1 (true) or 0 (false).

true — Ignore case when comparing names to the list of placenames.
false — Do not ignore case when comparing names to the list of placenames.

Output Arguments

collapse all

`geocodedGT` — Geocoded placenames and shapes
geospatial table

Geocoded placenames and shapes, returned as a geospatial table. The geospatial table contains a row for each matched placename in names.

When you use the installed list of placenames, the geospatial table contains two variables:

Shape — Shape of the matched placename, returned as a geopolyshape or geopointshape object. The type of object depends on the administration level of the matched placename.
- When the function matches the placename to a region, the shape is a geopolyshape object that depicts either a bounding box or an outline of the region.
- When the function matches the placename to a state, the shape is a geopolyshape object that depicts an outline of the state.
- When the function matches the placename to a city, the shape is a geopointshape object that depicts the location of the city.
Name — Matched placename, returned as a string scalar.

When you use a custom table of placenames by specifying the customNamesGT argument, the output geospatial table is a subset of the custom table. As a result, the output geospatial table has the same table variables as the custom table.

More About

collapse all

Geocoding

Geocoding is the process of converting addresses or other locations into geographic coordinates. The geocode function represents geocoded placenames using point, line, and polygon shape objects.

Algorithms

When you use the installed list of placenames and do not specify the adminlevel argument, the function searches for a specified placename using this strategy:

Search the list of supported regions for the placename.
If the placename does not match a supported region, then search the list of supported states.
If the placename does not match a supported state, then search the list of supported cities.

For example, this code matches the state of New York and not the city of New York.

geocode("New York")

Version History

Introduced in R2024b

geocode

Syntax

Description

Use Installed List of Placenames

Use Custom List of Placenames

Additional Options

Examples

Geocode World Regions

Geocode US States

Geocode World Cities

Geocode Custom Placenames

Geocode Custom Placenames Using Specified Table Variable

Input Arguments

`names` — Placenames
string scalar | vector of strings | character vector | cell array of character vectors

`adminlevel` — Administration level
`"region"` | `"state"` | `"city"`

`customNamesGT` — Custom placenames and shapes
geospatial table

`namevar` — Table variable containing custom placenames
string scalar | character vector | `pattern` object | numeric scalar | logical vector | `vartype()`

Name-Value Arguments

`PartialMatch` — Use partial string matching
`true` or `1` (default) | `false` or `0`

`IgnoreCase` — Ignore case
`true` or `1` (default) | `false` or `0`

Output Arguments

`geocodedGT` — Geocoded placenames and shapes
geospatial table

More About

Geocoding

Algorithms

Version History

See Also

Functions

Topics

geocode

Syntax

Description

Use Installed List of Placenames

Use Custom List of Placenames

Additional Options

Examples

Geocode World Regions

Geocode US States

Geocode World Cities

Geocode Custom Placenames

Geocode Custom Placenames Using Specified Table Variable

Input Arguments

names — Placenames string scalar | vector of strings | character vector | cell array of character vectors

adminlevel — Administration level "region" | "state" | "city"

customNamesGT — Custom placenames and shapes geospatial table

namevar — Table variable containing custom placenames string scalar | character vector | pattern object | numeric scalar | logical vector | vartype()

Name-Value Arguments

PartialMatch — Use partial string matching true or 1 (default) | false or 0

IgnoreCase — Ignore case true or 1 (default) | false or 0

Output Arguments

geocodedGT — Geocoded placenames and shapes geospatial table

More About

Geocoding

Algorithms

Version History

See Also

Functions

Topics

`names` — Placenames
string scalar | vector of strings | character vector | cell array of character vectors

`adminlevel` — Administration level
`"region"` | `"state"` | `"city"`

`customNamesGT` — Custom placenames and shapes
geospatial table

`namevar` — Table variable containing custom placenames
string scalar | character vector | `pattern` object | numeric scalar | logical vector | `vartype()`

`PartialMatch` — Use partial string matching
`true` or `1` (default) | `false` or `0`

`IgnoreCase` — Ignore case
`true` or `1` (default) | `false` or `0`

`geocodedGT` — Geocoded placenames and shapes
geospatial table