Main Content

Call Web Services from Functions

You can call webread from functions you define. Best practice is to allow your function to pass HTTP request options to webread.

This code sample shows how to download climate data for a country. The sample defines a function in a file named worldBankTemps.m that downloads annual temperatures from the World Bank and converts them to degrees Fahrenheit. You can pass additional HTTP request parameters with the options input argument. options is a weboptions object that worldBankTemps passes to webread. You can call worldBankTemps with a country name only when you do not need to define any other HTTP request parameters.

function temperatures = worldBankTemps(country,options)
% Get World Bank temperatures for a country, for example, 'USA'.
api = '';
api = [api 'country/cru/tas/year/'];
country = [api country];

% The options object contains additional HTTP
% request parameters. If worldBankTemps was
% not passed options as an input argument,
% create a default weboptions object.
if ~exist('options','var')
    options = weboptions;
s = webread(country,options);

% Convert data to arrays
temperatures = struct('Years',[],'DegreesInFahrenheit',[]);
temperatures(1).Years = [s.year];
temperatures(1).DegreesInFahrenheit = [];

% Convert temperatures to Fahrenheit
temperatures(1).DegreesInFahrenheit = temperatures(1).DegreesInFahrenheit * 9/5 + 32;

To get temperature data for the USA, call worldBankTemps. If the connection to the World Bank web service times out, the service returns an error message.

S = worldBankTemps('USA')
Error using webread (line 112)
The connection to 
URL '' 
timed out after 5.0 seconds. Set options.Timeout to a higher value.

If you create options and set its Timeout property to 60 seconds, then you can call worldBankTemps again with options as an input argument. worldBankTemps passes options to webread as an input argument. This time webread keeps the connection open for a maximum of 60 seconds.

options = weboptions('Timeout',60);
S = worldBankTemps('USA',options)
S = 

                  Years: [1x112 double]
    DegreesInFahrenheit: [1x112 double]

If your code does not allow you to pass request options to webread, that limits your ability to respond to error messages returned by web services.

Error Messages Concerning Web Service Options

When you use a web service function in MATLAB® the function might return an error message that advises you to set a property of options, such as options.Timeout. This table shows some typical error messages that refer to options properties and actions you can take in response.

Error Message Contains PhraseAction To Be Taken

Set options.Timeout to a higher value.

options = weboptions('Timeout',60)
data = webread(url,options)

Set options.ContentType to 'json'.

options = weboptions('ContentType','json')
data = webread(url,options)

. . . the provided authentication parameters, options.Username and options.Password, are incorrect.

options = weboptions('Username','your username','Password','your password')
data = webread(url,options)