RunMat
GitHub

View all functions

CategoryIo: Http

What does the webread function do in MATLAB / RunMat?

webread issues an HTTP or HTTPS request and returns the response body as a MATLAB-compatible value. Textual payloads become character vectors, JSON responses are decoded into structs, cells, and numeric arrays, while binary payloads return numeric vectors of bytes.

How does the webread function behave in MATLAB / RunMat?

  • Accepts URLs supplied as character vectors or string scalars; the URL must be absolute.
  • Optional weboptions-style fields (either through a struct argument or name-value pairs) control content decoding (ContentType), request timeout (Timeout), headers (HeaderFields), and authentication (Username/Password). The builtin currently supports the default GET request method; use webwrite for POST/PUT uploads.
  • Additional name-value pairs that do not match an option are appended to the query string using percent-encoding. A leading struct or cell array argument can also supply query parameters.
  • ContentType 'auto' (default) inspects the Content-Type response header to choose between JSON, text, or binary decoding. Explicit ContentType 'json', 'text', or 'binary' override the detection logic.
  • JSON responses are parsed with the same rules as jsondecode, producing doubles, logicals, strings, structs, and cell arrays that match MATLAB semantics.
  • Text responses preserve the server-provided character encoding (UTF-8 with automatic decoding of exotic charsets exposed in the HTTP headers). Binary payloads return 1×N double arrays whose entries store byte values in the range 0–255.
  • HTTP errors (non-2xx status codes), timeouts, TLS failures, and parsing problems raise descriptive MATLAB-style errors.

webread Function GPU Execution Behaviour

webread runs entirely on the CPU. Any gpuArray inputs (for example, query parameter values) are gathered to host memory before building the HTTP request. Results are produced on the host, and fusion graphs terminate at this builtin via ResidencyPolicy::GatherImmediately.

Examples of using the webread function in MATLAB / RunMat

Reading JSON data from a REST API

opts = weboptions("ContentType", "json", "Timeout", 15);
weather = webread("https://api.example.com/weather", opts, "city", "Reykjavik");
disp(weather.temperatureC);

Expected output:

    2.3

Downloading plain text as a character vector

html = webread("https://example.com/index.txt", "Timeout", 5);
extract = html(1:200);

extract contains the first 200 characters as a 1×200 char vector.

Retrieving binary payloads such as images

bytes = webread("https://example.com/logo.png", "ContentType", "binary");
filewrite("logo.png", uint8(bytes));

The PNG file is written locally after converting the returned bytes to uint8.

Supplying custom headers and credentials

headers = struct("Accept", "application/json", "X-Client", "RunMat");
data = webread("https://api.example.com/me", ...
               "Username", "ada", "Password", "secret", ...
               "HeaderFields", headers, ...
               "ContentType", "json");

Custom headers are merged into the request, and HTTP basic authentication credentials are attached.

Passing query parameters as a struct

query = struct("limit", 25, "sort", "name");
response = webread("https://api.example.com/resources", query, "ContentType", "json");

query is promoted into the URL query string before the request is sent.

GPU residency in RunMat (Do I need gpuArray?)

No. webread gathers any GPU-resident values before contacting the network and produces host results. Keeping inputs on the GPU offers no benefit because HTTP/TLS stacks operate on the CPU.

FAQ

  1. Can webread decode JSON automatically?
    Yes. When the server reports a JSON Content-Type header (for example application/json or application/vnd.api+json) the builtin decodes it using the same rules as jsondecode. Override the behaviour with "ContentType","text" or "ContentType","binary" when needed.

  2. How do I control request timeouts?
    Supply "Timeout", seconds as a name-value pair or in an options struct. The default timeout is 60 seconds. Timeouts raise webread: request to <url> timed out.

  3. What headers can I set?
    Use "HeaderFields", struct(...) or a cell array of name/value pairs. Header names must be valid HTTP tokens. The builtin automatically sets a RunMat-specific User-Agent string unless you override it with "UserAgent", "..."

  4. Does webread follow redirects?
    Yes. The underlying HTTP client follows redirects up to the platform default limit while preserving headers and authentication.

  5. How do I provide credentials?
    Use "Username", "user", "Password", "pass" for HTTP basic authentication. Supplying a password without a username raises an error.

  6. Can I send POST or PUT requests?
    webread is designed for read-only requests and currently supports the default GET method. Use webwrite (planned) for requests that include bodies or mutate server state.

  7. How are binary responses represented?
    Binary payloads return 1×N double arrays whose elements are byte values. Convert them to the desired integer type (for example uint8) before further processing.

  8. What happens when the server returns an error status?
    Non-success HTTP status codes raise webread: request to … failed with HTTP status XYZ. Inspect the remote server logs or response headers for additional diagnostics.

  9. Does webread support compressed responses?
    Yes. The builtin enables gzip / deflate content decoding through the HTTP client automatically.

  10. Can I pass query parameters as GPU arrays?
    Yes. Inputs wrapped in gpuArray are gathered before assembling the query string.

See Also

webwrite, weboptions, jsondecode, websave