WEBSERVICE

What it does

WEBSERVICE(url)

WEBSERVICE(url) issues a GET request for url and returns the response body as text.

Four properties follow from the documentation and matter more than the one-line description:

1. GET only. Microsoft's own error list constrains url to "the 2048 characters that are allowed for a GET request". There is no POST form, no header control, no body, no authentication argument. Anything an API needs beyond a URL cannot be expressed.
2. HTTP(S) only. Microsoft documents #VALUE! "for protocols that aren't supported, such as ftp:// or file://". WEBSERVICE is not a general fetcher.
3. The response is text, and unstructured. No parsing, no content-type handling. What comes back is a string; making sense of it is FILTERXML's job, or manual text surgery.
4. The cell text cap is a hard ceiling on the response. Microsoft documents #VALUE! when the arguments "result in a string that is not valid or that contains more than the allowable cell limit of 32767 characters". A response larger than one cell can hold is an error, not a truncation. Most real API responses exceed it.

Together these make WEBSERVICE a narrow instrument: small, public, GET-addressable, text-returning endpoints, on Windows Excel, with the URL fully specified up front.

Arguments

WEBSERVICE(url)

• url (required) — Microsoft: "The URL of the web service to be called".

The argument's admissible values are bounded by three documented limits at once: at most 2,048 characters (the GET limit), a supported protocol, and a result that fits in a cell. The misunderstanding worth naming is that url is not a template — there is no separate parameter list, so query parameters are built by concatenation, and any value interpolated into the URL must be percent-encoded first. Microsoft says so directly: "For the best results, the URL for WEBSERVICE should be encoded prior to inclusion in the formula", pointing at ENCODEURL.

Try it

This example needs an Excel service or external provider that OneCalc cannot supply in this preview.

Quirks

Result and edge cases

Text, or an error. Microsoft's page documents no other return kind.

The interesting edges are the ones that follow from a formula reaching the network, and the documentation addresses almost none of them:

• When does it fire? A formula that makes an HTTP request has to decide when to re-issue it. Whether WEBSERVICE is volatile, what triggers a re-fetch, and whether the result survives save/reopen without a recalculation are not stated on the function's page. This is the most consequential undocumented behaviour on this page, because it determines whether opening a workbook silently contacts a third-party server.
• Trust and blocking. External-data prompts, Protected View, and Trust Center policy all sit between the formula and the request. The value-universe chapter records #BLOCKED! and #CONNECT! as extended error codes for exactly this territory; whether WEBSERVICE produces either of them is not documented on its page and the Handbook does not know.
• Non-200 responses. Whether a 404 body is returned as text or collapses to #VALUE! is not stated.
• Encoding. How response bytes become UTF-16 text — declared charset, HTTP header, or assumption — is not stated.

Errors

Microsoft documents #VALUE! for all four of the following:

Everything collapses onto one error code. From #VALUE! alone a workbook cannot distinguish a typo, an oversized response, a dead host, and a blocked protocol — which makes WEBSERVICE unusually hard to debug from the grid, and makes any diagnostic wrapper around it a guess.

Availability is documented as: Excel for Microsoft 365, Excel 2024, 2021, 2019 and 2016, with Mac excluded — "The WEBSERVICE function may appear in the Excel for Mac function gallery, but it relies on Windows operating system features, so it will not return results on Mac."

How to implement

Notes for implementers

• This function is a security boundary, not just an I/O call. A worksheet formula that issues an outbound request can be used to exfiltrate cell contents in a query string, and the trigger is opening a file. Any implementation must decide deliberately about consent, caching, and whether requests fire on load; "match Excel" is not a sufficient specification because Excel's own answer here is governed by host policy rather than function semantics.
• Recalculation semantics are the specification. A pure-function model does not fit: the same argument may legitimately produce different results at different times, so the function's determinism class is a host contract rather than a kernel property.
• The 2,048-character limit is a documented Excel behaviour, not an HTTP rule, and must be enforced as such.
• Response decoding needs an explicit, stated policy. Guessing a charset produces mojibake that is indistinguishable, from the grid, from a server bug.

Rust code

This entry has no Rust implementation yet.

No implementation has been published with a Handbook test suite for this function.

Version differences

No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.

Alternatives

Relationships

• ENCODEURL — the documented preprocessor for any value interpolated into url.
• FILTERXML — the documented postprocessor for an XML response. The three functions are designed as a pipeline and Microsoft's examples always show them that way.
• Power Query / Get & Transform — the supported modern path for pulling data from the web into a workbook, with headers, authentication, paging, refresh control, and no 32,767-character ceiling. For anything beyond a toy endpoint this is the honest recommendation.
• HYPERLINK — confused with WEBSERVICE by name. HYPERLINK never fetches anything; it produces a clickable link.
• STOCKHISTORY and the linked data types — the other route by which modern Excel reaches external data, but through a Microsoft-operated provider rather than an arbitrary URL.

Named variants

No named variants are recorded yet.