webread

Read content from RESTful web service

Syntax

data = webread(url)

data = webread(url,QueryName1,QueryValue1,...,QueryNameN,QueryValueN)

data = webread(___,options)

[data,colormap,alpha] = webread(___)

[data,Fs] = webread(___)

Description

data = webread(url) reads content from the web service specified by url and returns the content in data.

The web service provides a RESTful that returns data formatted as an internet media type such as JSON, XML, image, or text.

data = webread(url,QueryName1,QueryValue1,...,QueryNameN,QueryValueN) appends query parameters to url, as specified by one or more pairs of name-value arguments. To put a query into the body of the message, use webwrite. The web service defines the query parameters.

data = webread(___,options) adds other HTTP request options, specified by the weboptions object options. You can use this syntax with any of the input arguments of the previous syntaxes.

To return data as a specific output type, specify the ContentType property of options.

To read content with a function, specify the ContentReader property of options as a handle to the function. webread downloads data from a web service and reads the data with the specified function:

• If you specify a handle to a function that returns multiple output arguments, webread returns all output arguments.

• If you specify a handle to a function that returns no output argument (such as Image Processing Toolbox™ function @implay for video files), webread returns no output argument.

[data,colormap,alpha] = webread(___) reads an image from the web service specified by url and returns the image in data. You can use the previous syntaxes to return the image only. Use this syntax to return the colormap and alpha channels associated with the image.

webread returns an image when the HTTP response has a Content-Type header field that specifies an image media type and if imread supports the image format. For supported image formats, see Supported File Formats for Import and Export.

[data,Fs] = webread(___) reads audio data from the web service specified by url and returns the audio data in data. You can use the previous syntaxes to return the audio data only. Use this syntax to return the sample rate of the audio data in hertz.

webread returns audio data when the HTTP response has a Content-Type header field that specifies an audio media type and if audioread supports the audio format. For supported audio formats, see Supported File Formats for Import and Export.

Examples

Read Image from Website

Read an image of Jupiter from the Hubble Heritage website and display it.

url = 'https://hubblesite.org/uploads/image_file/image_attachment/14836/compass_large_web.jpg';
rgb = webread(url);
whos rgb

  Name        Size                Bytes  Class    Attributes

  rgb       500x500x3            750000  uint8              

Resize and display the image.

rgb = imresize(rgb,0.6);
imshow(rgb)

Jupiter image courtesy of NASA, ESA, and the Hubble Heritage Team (STScI/AURA). For terms of use, see the Space Telescope Science Institute.

Read Data from Web Service API

Read temperature data for the USA from the World Bank Climate Data API. Plot temperatures from the years 1901–2012.

Read data from the World Bank. This API returns data as a JSON object.

api = 'http://climatedataapi.worldbank.org/climateweb/rest/v1/';
url = [api 'country/cru/tas/year/USA'];
S = webread(url)

S = 

112x1 struct array with fields:

    year
    data

webread converts the JSON object to a structure array. Each structure contains the year and the average temperature in the USA for that year, in degrees Celsius.

Display the temperature for the first year.

S(1)

ans = 

    year: 1901
    data: 6.6187

Plot the average temperatures. Concatenate S.year and S.data into arrays and plot them.

year = [S.year];
data = [S.data];
plot(year,data)
xlabel('Year');
ylabel('Temperature (Celsius)');
title('USA Average Temperatures')
axis tight

API and data courtesy of the World Bank: Climate Data API. (See World Bank: Climate Data API for more information about the API, and World Bank: Terms of Use.)

Specify Web Service Query Parameters

Search the File Exchange for files uploaded within the past seven days that contain the word Simulink^®.

Specify the query parameters. webread appends web service query parameter names and values to the URL. The File Exchange web service defines the term and duration query parameters, not the webread function.

url = 'https://www.mathworks.com/matlabcentral/fileexchange/';
data = webread(url,'term','simulink','duration',7);

webread returns the HTML for the search result page as a character array.

Specify Request Option

Specify an additional request option to read data from the World Bank Climate Data API to a character array.

Create a weboptions object and set its ContentType to 'text'. The webread function converts the JSON object to a character array instead of a structure array. Display the beginning of the character array.

api = 'http://climatedataapi.worldbank.org/climateweb/rest/v1/';
url = [api 'country/cru/tas/year/USA'];
options = weboptions('ContentType','text');
data = webread(url,options);
data(1:62)

ans =

[{"year":1901,"data":6.6187487},{"year":1902,"data":6.4643273}

API and data courtesy of the World Bank: Climate Data API. (See World Bank: Climate Data API for more information about the API, and World Bank: Terms of Use.)

Specify Date and Time as Query Parameters

Read a Blue Marble: Next Generation image for December 2004 from the NASA Earth Observation (NEO) Web Mapping Service.

Specify the date of the requested image with a datetime object. Specify the Format property of D so that the format matches the format required by the web service.

url = 'http://neowms.sci.gsfc.nasa.gov/wms/wms';
D = datetime(2004,12,01,'Format','yyyy-MM-dd');
rgb = webread(url,'Time',D, ...
     'Service','WMS','Layers','BlueMarbleNG-TB','CRS','CRS:84', ...
     'Format','image/jpeg','Height',256,'Width',512, ...
     'BBOX','-180.0,-90.0,180.0,90.0','Version','1.3.0','Request','GetMap');
imshow(rgb)

webread converts datetime objects so that they can be values of web service query parameters. All the name-value pairs in the example provide query parameters specified by the NEO Web Mapping Service.

Blue Marble: Next Generation + Topography and Bathymetry image courtesy of NASA’s Earth Observatory. Access to imagery and services provided by the NEO Web Mapping Service (WMS). (See NASA Earth Observations for credit and terms of use. For WMS query parameters, search the NASA Earth Observations site, WMS 1.3.0 Capabilities.)

Input Arguments

url — URL to web service

character vector | string scalar

URL to a web service, specified as a character vector or string scalar. Include the transfer protocol. Only http and https are supported. The web service implements a RESTful interface. See RESTful for more information.

Example: webread('https://www.mathworks.com/matlabcentral') reads the web page and returns its HTML as a character array.

QueryName1,QueryValue1,...,QueryNameN,QueryValueN — Web service query parameters

name-value pairs

Web service query parameters, specified as one or more pairs of name-value arguments. A QueryName argument must specify the name of a query parameter, as a character vector or string scalar. A QueryValue argument must be a character vector, a string scalar, or a numeric, logical, or datetime value that specifies the value of the query parameter. Numeric, logical, and datetime values can be in arrays. The web service defines name-value pairs that it accepts as part of a request.

When you specify QueryValue as a datetime object, you must specify its Format property so that it is consistent with the format required by the web service. If the Format property includes a time zone or offset, and the datetime object is not zoned, then webread specifies 'Local' as the time zone.

When QueryValue contains multiple values in an array, you might need to specify the ArrayFormat property of a weboptions object to form-encode the array as specified by the web service.

Example: webread('https://www.mathworks.com/matlabcentral/fileexchange/','term','webread') retrieves a list of files uploaded to the File Exchange that contain the word webread.

options — Additional HTTP request options

weboptions object

Additional HTTP request options, specified as a weboptions object.

You can specify the ContentType property of a weboptions object, and pass the object as an input argument to webread. Then webread returns data as that type of output. The table lists the valid content types you can specify in a weboptions object.

ContentType Specifier	Output Type
'auto' (default)	Output type automatically determined based on content type specified by the server.
'text'	Character vector for content types: text/plain text/html text/xml application/xml application/javascript application/x-javascript application/x-www-form-urlencoded If a web service returns a MATLAB® file with a .m extension, the function returns its content as a character vector.
'image'	Numeric or logical matrix for image/format content. If the first output argument is an indexed image, the second output argument is the colormap, and the third output argument is the alpha channel. For supported image formats, see Supported File Formats for Import and Export.
'audio'	Numeric matrix for audio/format content with numeric scalar sampling rate as a second output argument. For supported audio formats, see Supported File Formats for Import and Export.
'binary'	uint8 column vector for binary content (that is, content not to be treated as type char).
'table'	Scalar table object for spreadsheet and CSV (text/csv) content.
'json'	char, numeric, logical, structure, or cell array, for application/json content.
'xmldom'	Java® Document Object Model (DOM) node for text/xml or application/xml content. If not specified, the function returns XML content as a character vector.
'raw'	char column vector for 'text', 'xmldom', and 'json' content. The function returns any other content type as a uint8 column vector.

See weboptions for all request options that are weboptions properties.

Output Arguments

data — Content from web service

scalar | array | structure | table

Content read from a web service, returned as a scalar, array, structure, or table.

colormap — Colormap associated with indexed image

numeric array

Colormap associated with an indexed image, returned as a numeric array.

alpha — Alpha channels associated with indexed image

numeric array

Alpha channels associated with an indexed image, returned as a numeric array.

Fs — Sample rate of audio data in hertz

positive numeric scalar

Sample rate of audio data in hertz, returned as a positive numeric scalar.

More About

RESTful

REST means representational state transfer, a common architectural style for web services. RESTful interfaces provide standard HTTP methods such as GET, PUT, POST, or DELETE.

Tips

• For functionality not supported by the RESTful web services functions, see the HTTP Interface.

• webread supports HTTP GET and POST methods. Many web services provide both GET and POST methods to request data. To send an HTTP POST request, specify the RequestMethod property of options as 'post'. However, webread puts query options into the url, not in the body of the request message. To put a query into the body, use webwrite.

• For HTTP POST requests, the webread function supports only the application/x-www-form-urlencoded media type. To send a POST request with content of any other internet media type, use webwrite.

• This function does not examine the document contents to determine how to process it. For example, HTML and XML documents often contain a <meta> tag that specifies the document character encoding. If the encoding is different from the default webread encoding, then specify the correct CharacterEncoding option in weboptions.