websave

Save content from RESTful web service to file

collapse all in page

Syntax

outfilename = websave(filename,url)
outfilename = websave(filename,url,QueryName1,QueryValue1,...,QueryNameN,QueryValueN)
outfilename = websave(___,options)

Description

example

outfilename = websave(filename,url) saves content from the web service specified by url and writes it to filename. The websave function returns the full filename path as outfilename.

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

example

outfilename = websave(filename,url,QueryName1,QueryValue1,...,QueryNameN,QueryValueN) appends query parameters to url, as specified by one or more pairs of name-value arguments. The web service defines the query parameters.

example

outfilename = websave(___,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.

websave supports HTTP GET and POST methods. To send an HTTP POST request, specify the RequestMethod property of options as 'post'. Many web services provide both GET and POST methods to request data.

Examples

collapse all

Save an image of Jupiter from the Hubble Heritage website.

url = 'https://hubblesite.org/uploads/image_file/image_attachment/14836/compass_large_web.jpg';
filename = 'jupiter_aurora.jpg';
outfilename = websave(filename,url)

outfilename =

C:\Libraries\Documents\jupiter_aurora.jpg

websave saves the image as a JPEG file, as specified by the Hubble web service, even when you give filename a different extension. (Jupiter image courtesy of NASA, ESA, and the Hubble Heritage Team (STScI/AURA). For terms of use, see the Space Telescope Science Institute).

Search File Exchange for files uploaded within the past seven days that contain the word Simulink® and display the results of the search.

url = 'https://www.mathworks.com/matlabcentral/fileexchange/';
filename = 'simulink_search.html';
outfilename = websave(filename,url,'term','simulink','duration',7)
outfilename =

C:\Libraries\Documents\simulink_search.html

Display the HTML file in a web browser.

web(outfilename)

Save sunspot data from the National Geophysical Data Center (NGDC) to an ASCII file. Use a weboptions object to set the timeout value to Inf so that the connection does not time out.

api = 'http://www.ngdc.noaa.gov/stp/space-weather/';
url = [api 'solar-data/solar-indices/sunspot-numbers/' ...
       'american/lists/list_aavso-arssn_yearly.txt'];
filename = 'sunspots_annual.txt';
options = weboptions('Timeout',Inf);
outfilename = websave(filename,url,options)

outfilename =

C:\Libraries\Documents\sunspots_annual.txt

Aggregated data and web service courtesy of the NGDC. Sunspot data courtesy of the American Association of Variable Star Observers (AAVSO), originally published in AAVSO Sunspot Counts: 1943-2013, AAVSO Solar Section (R. Howe, Chair). (See NGDC Privacy Policy, Disclaimer, and Copyright for NGDC terms of use, and AAVSO Solar Section for AAVSO terms of use.)

Save the 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');
filename = 'BlueMarble.jpg';
outfilename = websave(filename,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')

outfilename =

C:\Libraries\Documents\BlueMarble.jpg

websave 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.)

Read JSON data from a website and save in file test.txt.

uri = matlab.net.URI('http://httpbin.org/get');
websave('test.txt',uri,weboptions('ContentType','json'));

Read the text from the file into a structure of JSON data.

js = jsondecode(fileread('test.txt'))
js = 

  struct with fields:

       args: [1×1 struct]
    headers: [1×1 struct]
     origin: '144.444.4.4'
        url: 'http://httpbin.org/get'

Input Arguments

collapse all

Name of file to save content to, specified as a character vector or string scalar. websave saves the content as is. websave ignores options.ContentType and options.ContentReader, even if these properties are set.

Example: websave('matlabcentral.html','https://www.mathworks.com/matlabcentral') reads the web page and saves its HTML to the file matlabcentral.html.

URL to a web service, specified as a character vector or string scalar. The web service implements a RESTful interface. See RESTful for more information.

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. 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 to be 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 websave 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: websave('webread_search.html','https://www.mathworks.com/matlabcentral/fileexchange/','term','simulink') retrieves a list of files uploaded to the File Exchange that contain the word simulink and saves the search results to an HTML file.

Additional HTTP request options, specified as a weboptions object. For all request options that are weboptions properties, see weboptions.

More About

collapse all

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.

  • For HTTP POST requests, the websave 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.

See Also

| | |

Topics

External Websites

Introduced in R2014b

MATLAB Documentation

Support