Main Content

wmsfind

Search local database for Web map servers and layers

collapse all in page

Syntax

layers = wmsfind(querystr)
layers = wmsfind(querystr,Name,Value)

Description

layers = wmsfind(querystr) searches the fields of the installed WMS Database for partial matches of querystr, which is a string, string array, character vector, or cell array of character vectors. By default, wmsfind searches the Layer or LayerName properties but you can include other fields in the search using the SearchFields parameter.

wmsfind returns layers, an array of WMSLayer objects containing one object for each layer whose name or title partially matches querystr. WMS servers produce maps of spatially referenced raster data, such as temperature or elevation, that are known as layers.

example

layers = wmsfind(querystr,Name,Value) modifies the search of the WMS Database based on the values of the parameters. You can abbreviate parameter names and case does not matter.

Examples

collapse all

Open Live Script

Search the WMS Database for temperature data.

layers = wmsfind('temperature');

The wmsfind function searches both the LayerName and LayerTitle fields of the WMS Database for partial matches. The function returns an array of WMSLayer objects, which contains one object for each layer whose name or title partially matches 'temperature'.

Refine the search to include temperature data from NOAA. Display information about the first layer.

layersNOAA = refine(layers,'noaa');
layersNOAA(1)
ans = 
  WMSLayer

  Properties:
           Index: 1
     ServerTitle: 'WMS for SST and SST Anomaly, NOAA Global Coral Bleaching Monitoring, 5km, V.3.1, Monthly, 1985-Present'
       ServerURL: 'https://coastwatch.pfeg.noaa.gov/erddap/wms/NOAA_DHW_monthly/request?'
      LayerTitle: 'SST and SST Anomaly, NOAA Global Coral Bleaching Monitoring, 5km, V.3.1, Monthly, 1985-Present - sea_surface_temperature'
       LayerName: 'NOAA_DHW_monthly:sea_surface_temperature'
          Latlim: [-89.9750 89.9750]
          Lonlim: [-179.9750 179.9750]

  Methods

A WMSLayer object contains three properties that do not appear in the WMS Database: Abstract, CoordRefSysCodes, and Details. Populate these properties by using the wmsupdate function.

updatedLayers = wmsupdate(layersNOAA(1));
updatedLayers(1) 
ans = 
  WMSLayer

  Properties:
           Index: 1
     ServerTitle: 'WMS for SST and SST Anomaly, NOAA Global Coral Bleaching Monitoring, 5km, V.3.1, Monthly, 1985-Present'
       ServerURL: 'https://coastwatch.pfeg.noaa.gov/erddap/wms/NOAA_DHW_monthly/request?'
      LayerTitle: 'SST and SST Anomaly, NOAA Global Coral Bleaching Monitoring, 5km, V.3.1, Monthly, 1985-Present - sea_surface_temperature'
       LayerName: 'NOAA_DHW_monthly:sea_surface_temperature'
          Latlim: [-89.9750 89.9750]
          Lonlim: [-179.9750 179.9750]
        Abstract: ''
CoordRefSysCodes: {'EPSG:4326'}
         Details: [1x1 struct]

  Methods

Your results might be different because the WMS Database changes each release.

Open Live Script

Search the Entire WMS Database

Search the WMS database for layers that contain the word "temperature". The wmsfind function returns an array of WMSLayer objects.

layers = wmsfind('temperature');

Find layers that contain global temperature data. The query includes the asterisk wildcard character '*'. 

layers = wmsfind('global*temperature');

Search Specific Fields in the WMS Database

Search the LayerTitle field for all layers that contain an exact match for the term 'Rivers'. You must use the MatchType parameter to specify an exact match.

layers = wmsfind('Rivers','MatchType','exact', ...
                 'IgnoreCase',false,'SearchFields','layertitle');

Search the LayerName field for all layers that contain a partial match for 'elevation'. By default, wmsfind searches for partial matches.

layers = wmsfind('elevation','SearchFields','layername');

Search the LayerName field for all unique servers that contain 'BlueMarbleNG'.

layers = wmsfind('BlueMarbleNG','SearchFields','layername', ...
                 'MatchType','exact');
urls = servers(layers);

Limit Your Search to Specific Geographic Regions

Find layers that contain elevation data for Colorado. Use the Latlim and Lonlim parameters to specify the location.

latlim = [35 43];
lonlim = [-111 -101];
layers = wmsfind('elevation','Latlim',latlim,'Lonlim',lonlim);

Find all layers that contain temperature data for a point in Perth, Australia. Use the Latlim and Lonlim parameters to specify the location.

lat = -31.9452;
lon = 115.8323;
layers = wmsfind('temperature','Latlim',lat,'Lonlim',lon);

Find all the unique URLs of all government servers.

layers = wmsfind('*.gov*','SearchFields','serverurl');
urls = servers(layers);

Search Multiple Fields at the Same Time and Refine Your Search

Search both the LayerTitle and the LayerName fields for all the layers that contain the word "temperature".

fields = [string('layertitle') string('layername')];
temperature = wmsfind('temperature','SearchFields',fields);

Refine the results of your temperature search to find only those layers that deal with sea surface temperatures. Use the WMSLayer object refine method.

sst = refine(temperature,'sea surface');

Refine your sea surface temperature search further to find only those layers that deal with global sea surface temperatures.

global_sst = refine(sst,'global');

Search the Entire WMS Database and Progressively Refine Your Search

Note that finding all the layers from the WMS database may take several seconds to execute and require a substantial amount of memory. The database contains more than 100,000 layers.

Find all the layers in the WMS database and sort them into a set that comprises only the unique layer titles. 

layers = wmsfind('*');
layerTitles = sort(unique({layers.LayerTitle}))';

Refine your original search, layers, to include only those layers with global coverage. Use the WMSLayer object refineLimits method.

global_layers = refineLimits(layers, ...
                             'Latlim',[-90 90],'Lonlim',[-180 180]);

Refine the results of your global layers search to contain only layers with global extent that include the word "topography". Use the WMSLayer object refine method.

global_topography_layers = refine(global_layers,'topography');

Refine your original search, layers, to contain only layers that have some combination of the terms "oil" and "gas" in the LayerTitle field.

oil_gas_layers = refine(layers,'oil*gas','SearchFields','layertitle');
Open Live Script

Search the WMS database for layers containing the word "elevation". Search the online version of the database by specifying the Version argument as "online". If you do not specify the version, then wmsfind reads from the installed database.

elevation = wmsfind("elevation",Version="online");

Input Arguments

collapse all

Characters to search for in WMS Database fields, specified as a string scalar, string array, character vector, or cell array of character vectors. querystr can contain the asterisk wildcard character (*).

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: [A,R] = wmsfind('elevation','SearchFields','layername');

Ignore case when comparing field values to querystr, specified as the logical value true or false.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical

Latitudinal limits of the search, specified as a two-element vector of the form [southern_limit northern_limit] or a scalar value representing the latitude of a single point. Values are in the range [-90, 90]. All angles are in units of degrees. If provided and not empty, a given layer appears in the results only if its limits fully contain the specified 'Latlim' limits. Partial overlap does not result in a match.

Data Types: double | int16 | int32 | int64 | int8 | single | uint8 | uint16 | uint32 | uint64

Longitudinal limits of the search, specified as a two-element vector of the form [western_limit eastern_limit] or scalar value representing the longitude of a single point. All angles are in units of degrees. If provided and not empty, a given layer appears in the results only if its limits fully contain the specified 'Lonlim' limits. Partial overlap does not result in a match.

Data Types: double | int16 | int32 | int64 | int8 | single | uint8 | uint16 | uint32 | uint64

Strictness of match, specified as the character vector or string 'partial' or 'exact'. If 'MatchType' is 'exact' and querystr is '*', a match occurs when the search field matches the character '*'.

Data Types: char | string

Fields to search in the WMS Database, specified as a character vector, cell array of character vectors, string, or array of strings. The function searches the values of the specified fields in the WMS Database for a partial or exact match with querystr. The following table lists valid values.

FieldBehavior
'layername'Search the LayerName field in the WMS Database. The layer name is an abbreviated form of the LayerTitle field and is the keyword the server uses to retrieve the layer.
'layertitle'Search the LayerTitle field in the WMS Database. The layer title includes descriptive information about a layer and facilitates understanding the meaning of the raster values of the layer.
'layer'Search both the LayerTitle and the LayerName fields.
'servertitle'Search the ServerTitle field in the WMS Database. A server title includes descriptive information about the server.
'serverurl'Search the ServerURL field in the WMS Database. The server URL and layer information facilitate the reading of raster layers by the function wmsread.
'server'Search both the ServerTitle and the ServerURL fields.
'any'Search all fields.

Data Types: char | cell | string

Version of the WMS Database to read, specified as one of the following values.

ValueDescription
'installed'Read from the installed database. This is the default. The information found in the installed database is static and is not automatically updated—it was validated at the time of the software release.
'online'

Read from the version of the database hosted on the MathWorks website. This version of the database contains more up-to-date information about servers because it is updated regularly. Note, however, that searching this online database requires a connection to the Internet.

If your network uses a firewall or another method of protection that restricts Internet access, you can provide information about your proxy server to MATLAB®. For more information, see Proxy Server Authentication.

'custom'Read from the wmsdatabase.mat file on the MATLAB path, such as from a previous release.

Data Types: char | string

Output Arguments

collapse all

Layers that match search criteria, returned as an array of WMSLayer objects, one for each layer found.

More About

collapse all

WMS Database

Mapping Toolbox™ contains a database of over 1000 stored WMS servers and over 100,000 layers. MathWorks® creates this database, called the WMS Database, by conducting a series of Internet searches and qualifying the search results.

Note

MathWorks does not guarantee the stability or accuracy of WMS data. The servers listed in the WMS Database are located on the Internet and are independent from MathWorks. Occasionally, you might receive error messages from servers experiencing difficulties. Servers might go down or become unavailable.

The wmsfind function is the only function that accesses the stored WMS Database. By default, the wmsfind function searches the WMS Database that is installed with the product. You can search a version of the WMS Database hosted on the MathWorks website or a WMS Database from a previous release by using the Version name-value argument. The information in the WMS Database installed with the product is static. The web-hosted database is updated regularly.

The WMS Database contains these fields:

Field NameData TypeField Content
ServerTitleCharacter vectorTitle of the WMS server, descriptive information about the server
ServerURLCharacter vectorURL of the WMS server
LayerTitle Character vectorTitle of the layer, descriptive information about the layer
LayerNameCharacter vectorName of the layer, keyword the server uses to retrieve the layer
LatlimTwo-element vectorSouthern and northern latitude limits of the layer
LonlimTwo-element vectorWestern and eastern longitude limits of the layer

The LayerTitle and LayerName fields sometimes have the same values. The LayerName field indicates a code used by the servers, such as '29:2', while the LayerTitle field provides more descriptive information. For example, 'Elevation and Rivers with Backdrop' might be an entry in the LayerTitle field.

Tips

  • The WMSLayer objects returned by wmsfind contain properties with the same names as the field names of the WMS Database, along with three additional properties: 'Abstract', 'CoordRefSysCodes', and 'Details'. The WMS Database does not contain information about these properties. To get this information about a server, you must use the wmsupdate function which updates these properties of the WMSLayer object by downloading information from the server. To view these properties, use the WMSLayer.disp method, specifying the 'Properties' parameter value 'all'. If you want to know more about a WMS server, use the wmsinfo function with the specific server URL.

Version History

Introduced in R2009b

See Also

| | | |

Topics