webread — Download web content (JSON, text, or binary) over HTTP/HTTPS.
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 webread works in 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 defaultGETrequest method; usewebwritefor 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 theContent-Typeresponse header to choose between JSON, text, or binary decoding. ExplicitContentType '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×Ndouble 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.
How webread runs on the GPU
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.
GPU memory and residency
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.
Examples
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.3Downloading plain text as a character vector
html = webread("https://example.com/index.txt", "Timeout", 5);
extract = html(1:200)Retrieving binary payloads such as images
bytes = webread("https://example.com/logo.png", "ContentType", "binary");
filewrite("logo.png", uint8(bytes))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")Passing query parameters as a struct
query = struct("limit", 25, "sort", "name");
response = webread("https://api.example.com/resources", query, "ContentType", "json")FAQ
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.
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.
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", "..."
Does webread follow redirects?
Yes. The underlying HTTP client follows redirects up to the platform default limit while preserving headers and authentication.
How do I provide credentials?
Use "Username", "user", "Password", "pass" for HTTP basic authentication. Supplying a password without a username raises an error.
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.
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.
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.
Does webread support compressed responses?
Yes. The builtin enables gzip / deflate content decoding through the HTTP client automatically.
Can I pass query parameters as GPU arrays?
Yes. Inputs wrapped in gpuArray are gathered before assembling the query string.
Related functions to explore
These functions work well alongside webread. Each page has runnable examples you can try in the browser.
webwrite, weboptions, jsondecode, websave
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how webread works, line by line, in Rust.
- View webread.rs on GitHub
- Learn how the runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code — faster, on any GPU, with no license required.
- Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
- Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
- A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.