#### 36.4.2 WWW Access ¶

Octave can communicate with websites across the Internet. The `web` function will launch an external web browser to interactively view a site. The remaining functions—`urlread`, `urlwrite`, `webread`, `webwrite`—are internal Octave functions which can import or export data to/from Octave and a website identified by a URL (Uniform Resource Locator).

`status =` web `()` ¶
`status =` web `(url)` ¶
`status =` web `(url, option)` ¶
`status =` web `(url, option_1, …, option_N)` ¶
`[status, h, url] =` web `(…)` ¶

  Open url in the default system web browser.

  With no arguments given, the address https://www.octave.org is opened.

  Additional options can be passed for MATLAB compatibility, but are ignored.

  - ‘`-browser`’ Open url in the default system browser.
  - ‘`-new`’ No effect on the system browser.
  - ‘`-noaddressbox`’ No effect on the system browser.
  - ‘`-notoolbar`’ No effect on the system browser.

  The return value status has one of the values:

  - ‘`0`’ Found and opened system browser successfully.
  - ‘`1`’ Cannot find the system browser.
  - ‘`2`’ System browser found, but an error occurred.

  The return values handle and url are currently unimplemented but given for compatibility.

  See also: weboptions, webread, webwrite, urlread, urlwrite.

`s =` urlread `(url)` ¶
`s =` urlread `(url, Name, Value, …)` ¶
`[s, success] =` urlread `(url, …)` ¶
`[s, success, message] =` urlread `(url, …)` ¶

  Download a remote file specified by its url and return its content in string s.

  For example:

      s = urlread ("http://ftp.octave.org/pub/README");

  The variable success is 1 if the download was successful, otherwise it is 0 in which case message contains an error message.

  If no output argument is specified and an error occurs, then the error is signaled through Octave’s error handling mechanism.

  This function uses libcurl. The curl library supports, among others, the HTTP, FTP, and FILE protocols. Username and password may be specified in the URL. For example:

      s = urlread ("http://user:password@example.com/file.txt");

  Additional options can be specified using property/value pairs:

  `Get`

    Cell array of name/value pairs for GET request parameters.

  `Post`

    Cell array of name/value pairs for POST request parameters.

  `Timeout`

    Timeout value in seconds.

  `UserAgent`

    User agent string for the request.

  `Username`

    Username for authentication.

  `Password`

    Password for authentication.

  `Charset`

    Character encoding (stored but not currently used).

  Example with property/value pairs:

      s = urlread ("http://www.example.com/data",
                   "Get", {"term", "octave"}, "Timeout", 10);

  For backward compatibility, the old calling form is also supported:

      s = urlread ("http://www.google.com/search",
                   "get", {"query", "octave"});

  See also: urlwrite, weboptions.

urlwrite `(url, localfile)` ¶
urlwrite `(url, localfile, Name, Value, …)` ¶
`f =` urlwrite `(url, localfile, …)` ¶
`[f, success] =` urlwrite `(url, localfile, …)` ¶
`[f, success, message] =` urlwrite `(url, localfile, …)` ¶

  Download a remote file specified by its url and save it as localfile.

  For example:

      urlwrite ("http://ftp.octave.org/pub/README",
                "README.txt");

  The full path of the downloaded file is returned in f.

  The variable success is 1 if the download was successful, otherwise it is 0 in which case message contains an error message.

  If no output argument is specified and an error occurs, then the error is signaled through Octave’s error handling mechanism.

  This function uses libcurl. The curl library supports, among others, the HTTP, FTP, and FILE protocols. Username and password may be specified in the URL, for example:

      urlwrite ("http://username:password@example.com/file.txt",
                "file.txt");

  Additional options can be specified using property/value pairs:

  `Get`

    Cell array of name/value pairs for GET request parameters.

  `Post`

    Cell array of name/value pairs for POST request parameters.

  `Timeout`

    Timeout value in seconds.

  `UserAgent`

    User agent string for the request.

  `Username`

    Username for authentication.

  `Password`

    Password for authentication.

  Example with property/value pairs:

      urlwrite ("http://www.example.com/data.txt", "data.txt",
                "Timeout", 10, "UserAgent", "Octave");

  For backward compatibility, the old calling form is also supported:

      urlwrite ("http://www.google.com/search", "search.html",
                "get", {"query", "octave"});

  See also: urlread, weboptions.

`response =` webread `(url)` ¶
`response =` webread `(url, name1, value1, …)` ¶
`response =` webread `(…, options)` ¶

  Read content from RESTful web service.

  Read content from the web service specified by url and return the content in response.

  All name-value pairs given (name1, value1, …) are appended as query parameters to url. To place a query in the body of the message, use `webwrite`. The web service defines the acceptable query parameters.

  options is a `weboptions` object that may be used to add other HTTP request options. This argument can be used with either calling form. See `help weboptions` for a complete list of supported HTTP options.

  See also: weboptions, webwrite.

`response =` webwrite `(url, name1, value1, …)` ¶
`response =` webwrite `(url, data)` ¶
`response =` webwrite `(…, options)` ¶

  Write data to RESTful web services.

  Write content to the web service specified by url and return the response in response.

  All name-value pairs given (name1, value1, …) are added as pairs of query parameters to the body of request method (`get`, `post`, `put`, etc.).

  options is a `weboptions` object that may be used to add other HTTP request options. This argument can be used with either calling form. See `help weboptions` for a complete list of supported HTTP options.

  See also: weboptions, webread.

`options =` weboptions `()` ¶
`options =` weboptions `(name1, value1, …)` ¶

  Specify parameters for RESTful web services.

  When called with no inputs return a default `weboptions` object to specify parameters for a request to a web service. A `weboptions` object is an optional input argument to the `webread` and `webwrite` functions.

  Multiple name and value pair arguments may be specified in any order as name1, value1, name2, value2, etc.

  The option names must match exactly one of those specified in the table below.

  The following options are available:

  - ‘`CharacterEncoding`’ — Specify the character encoding of the data:

    ‘`auto`’ (default), ‘`UTF-8`’, ‘`US-ASCII`’. ‘`auto`’ chooses an encoding based on the content-type of the data.

  - ‘`UserAgent`’ — Specify the User Agent for the connection.

    Default value is ‘`Octave/VERSION`’, where ‘`VERSION`’ is the current version of Octave as returned by `version`.

  - ‘`Timeout`’ — Specify the timeout value for the connection in seconds.

    Default is 5 seconds. The special value ‘`Inf`’ sets the timeout to the maximum value of 2147.483647 seconds.

  - ‘`Username`’ — User identifier for a basic HTTP connection.

    Default is `""`. It must be a string or character vector.

  - ‘`Password`’ — User authentication password for HTTP connection.

    Default is `""`. It must be a string or character vector.

    Programming Note: If you display a `weboption` object with the Password property set, the value is displayed as a string containing `'*'`. However, the object stores the value of the Password property as plain text.

  - ‘`KeyName`’ — Specify the name of an additional key to be added to the HTTP request header.

    It must be a string or character vector. It should be coupled with ‘`KeyValue`’.

  - ‘`KeyValue`’ — Specify the value of the key ‘`KeyName`’.

    ‘`KeyName`’ must already be assigned in order to specify this field.

  - ‘`ContentType`’ — Specify the content type of the data.

    The following values are available: ‘`auto`’, ‘`text`’, ‘`json`’

    Default is ‘`auto`’. It automatically determines the content type. All other formats like ‘`audio`’, ‘`binary`’, etc. available in MATLAB are not currently supported.

  - ‘`ContentReader`’ — Not yet implemented. Only for MATLAB compatibility.
  - ‘`MediaType`’ — Not yet implemented. Only for MATLAB compatibility.
  - ‘`RequestMethod`’ — Specifies the type of request to be made.

    The following methods are available: ‘`get`’, ‘`put`’, ‘`post`’, ‘`delete`’, ‘`patch`’

    `webread` uses the HTTP GET method. `webwrite` uses the HTTP POST method as default.

  - ‘`ArrayFormat`’ – Not yet implemented. Only for MATLAB compatibility.
  - ‘`HeaderFields`’ — Specify header fields for the connection.

    Names and values of header fields, specified as an m-by-2 cell array of strings, to add to the HTTP request header. `HeaderFields{i,1}` is the name of a field and `HeaderFields{i,2}` is its value.

        weboptions ("HeaderFields",
                    {"Content-Length", "78" ;
                     "Content-Type", "application/json"})

    creates a weboptions object that contains two header fields: `Content-Length` with value `78` and `Content-Type` with value `application/json`.

  - ‘`CertificateFilename`’ — Not yet implemented. Only for MATLAB compatibility.

  See also: webread, webwrite.