wmsfind

Search local database for Web map servers and layers

Syntax

layers = wmsfind(querystr)

layers = wmsfind(querystr,Name,Value)

Description

layers = wmsfind(querystr) searches the fields of the installed Web Map Service (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.

By default, wmsfind searches the WMS database installed with the product. Using the optional Version parameter, you can search a database from a previous release or search a version of the WMS database hosted on MathWorks^® website. The information found in the installed database was validated at the time of the software release and is not automatically updated. The web-hosted database provides more up-to-date information about servers because it is updated regularly. Note, however, that searching the web-hosted database requires a connection to the Internet.

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

Search the WMS Database for Layers

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');

Search Online Version of WMS Database

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

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

Input Arguments

querystr — Characters to search for in WMS database fields

string scalar | string array | character vector | cell array of character vectors

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 Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

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

'IgnoreCase' — Ignore case when comparing field values to querystr

true (default) | false

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

'Latlim' — Latitudinal limits of the search

two-element numeric vector | numeric scalar

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

'Lonlim' — Longitudinal limits of the search

two-element numeric vector | numeric scalar

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

'MatchType' — Strictness of match

'partial' (default) | 'exact'

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

'SearchFields' — Fields to search in the WMS database

'layer' (default) | 'server' | 'layertitle' | 'layername' | 'servertitle' | 'serverurl' | 'any'

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.

Field	Behavior
'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' — Version of the WMS database to read

'installed' (default) | 'online' | 'custom'

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

Value	Description
'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.
'custom'	Read from the wmsdatabase.mat file on the MATLAB path, such as from a previous release.

Data Types: char | string

Output Arguments

layers — Layers that match search criteria

WMSLayer objects

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

Tips

• TheWMSLayer 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.