{ "category": "Web functions", "display_name": "WEBSERVICE", "entry_kind": "built_in_function", "eval_api": { "method": "POST", "url": "https://handbook.dnacalc.com/api/eval" }, "function_id": "FUNC.WEBSERVICE", "implementation_state": { "answer_bank": null, "detail": "No catalogue row at this commit. WEBSERVICE fetches from the URL in the workbook, not from a Microsoft back end, and is being implemented as an ordinary function.", "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87", "in_catalogue": false, "state": "refuses", "state_label": "Refuses or not implemented", "summary": "Not yet implemented", "workbook_corpus": null }, "implementations": [], "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.WEBSERVICE.json", "name": "WEBSERVICE", "notes": [], "schema": "efh.function-reference/v1", "section_order": [ "what-it-does", "try-it", "quirks", "how-to-implement", "version-differences", "alternatives" ], "sections": { "alternatives": "\n### Relationships\n\n\n- **`ENCODEURL`** — the documented preprocessor for any value interpolated into `url`.\n- **`FILTERXML`** — the documented postprocessor for an XML response. The three functions are\n designed as a pipeline and Microsoft's examples always show them that way.\n- **Power Query / Get & Transform** — the supported modern path for pulling data from the web\n into a workbook, with headers, authentication, paging, refresh control, and no 32,767-character\n ceiling. For anything beyond a toy endpoint this is the honest recommendation.\n- **`HYPERLINK`** — confused with `WEBSERVICE` by name. `HYPERLINK` never fetches anything; it\n produces a clickable link.\n- **`STOCKHISTORY`** and the linked data types — the other route by which modern Excel reaches\n external data, but through a Microsoft-operated provider rather than an arbitrary URL.\n\n\n", "how-to-implement": "\n### Notes for implementers\n\n\n- This function is a security boundary, not just an I/O call. A worksheet formula that issues\n an outbound request can be used to exfiltrate cell contents in a query string, and the\n trigger is opening a file. Any implementation must decide deliberately about consent,\n caching, and whether requests fire on load; \"match Excel\" is not a sufficient specification\n because Excel's own answer here is governed by host policy rather than function semantics.\n- Recalculation semantics are the specification. A pure-function model does not fit: the same\n argument may legitimately produce different results at different times, so the function's\n determinism class is a host contract rather than a kernel property.\n- The 2,048-character limit is a documented Excel behaviour, not an HTTP rule, and must be\n enforced as such.\n- Response decoding needs an explicit, stated policy. Guessing a charset produces mojibake that\n is indistinguishable, from the grid, from a server bug.\n\n\n", "quirks": "\n### Result and edge cases\n\n\nText, or an error. Microsoft's page documents no other return kind.\n\nThe interesting edges are the ones that follow from a formula reaching the network, and the\ndocumentation addresses almost none of them:\n\n- **When does it fire?** A formula that makes an HTTP request has to decide when to re-issue\n it. Whether `WEBSERVICE` is volatile, what triggers a re-fetch, and whether the result\n survives save/reopen without a recalculation are not stated on the function's page. This is\n the most consequential undocumented behaviour on this page, because it determines whether\n opening a workbook silently contacts a third-party server.\n- **Trust and blocking.** External-data prompts, Protected View, and Trust Center policy all\n sit between the formula and the request. The value-universe chapter records `#BLOCKED!` and\n `#CONNECT!` as extended error codes for exactly this territory; whether `WEBSERVICE` produces\n either of them is not documented on its page and the Handbook does not know.\n- **Non-200 responses.** Whether a 404 body is returned as text or collapses to `#VALUE!` is\n not stated.\n- **Encoding.** How response bytes become UTF-16 text — declared charset, HTTP header, or\n assumption — is not stated.\n\n\n\n### Errors\n\n\nMicrosoft documents `#VALUE!` for all four of the following:\n\n| Condition | As documented |\n|---|---|\n| the arguments cannot return the data | \"If arguments are unable to return the data\" |\n| result too large or invalid | more than \"the allowable cell limit of 32767 characters\" |\n| URL too long | more than \"the 2048 characters that are allowed for a GET request\" |\n| unsupported protocol | \"such as `ftp://` or `file://`\" |\n\nEverything collapses onto one error code. From `#VALUE!` alone a workbook cannot distinguish a\ntypo, an oversized response, a dead host, and a blocked protocol — which makes `WEBSERVICE`\nunusually hard to debug from the grid, and makes any diagnostic wrapper around it a guess.\n\nAvailability is documented as: Excel for Microsoft 365, Excel 2024, 2021, 2019 and 2016, with\nMac excluded — \"The WEBSERVICE function may appear in the Excel for Mac function gallery, but\nit relies on Windows operating system features, so it will not return results on Mac.\"\n\n\n", "sources": "- Microsoft, \"WEBSERVICE function\" —\n \n (syntax, the `url` argument, all four documented `#VALUE!` conditions with their exact\n wording, the encode-first recommendation, the version list, and the Mac availability\n statement).\n- Microsoft, \"ENCODEURL function\" —\n \n (the composed `WEBSERVICE`/`FILTERXML` examples).\n- Handbook `data/presence/FUNC.WEBSERVICE.json` — no implementation module, no dispatch entry.\n\n\n", "version-differences": "No comparison between specific Excel builds is recorded here yet. This does not establish that all builds behave alike.", "what-it-does": "\n`WEBSERVICE(url)` issues a **GET** request for `url` and returns the response body as text.\n\nFour properties follow from the documentation and matter more than the one-line description:\n\n1. **GET only.** Microsoft's own error list constrains `url` to \"the 2048 characters that are\n allowed for a GET request\". There is no POST form, no header control, no body, no\n authentication argument. Anything an API needs beyond a URL cannot be expressed.\n2. **HTTP(S) only.** Microsoft documents `#VALUE!` \"for protocols that aren't supported, such\n as `ftp://` or `file://`\". `WEBSERVICE` is not a general fetcher.\n3. **The response is text, and unstructured.** No parsing, no content-type handling. What comes\n back is a string; making sense of it is `FILTERXML`'s job, or manual text surgery.\n4. **The cell text cap is a hard ceiling on the response.** Microsoft documents `#VALUE!` when\n the arguments \"result in a string that is not valid or that contains more than the allowable\n cell limit of 32767 characters\". A response larger than one cell can hold is an error, not a\n truncation. Most real API responses exceed it.\n\nTogether these make `WEBSERVICE` a narrow instrument: small, public, GET-addressable,\ntext-returning endpoints, on Windows Excel, with the URL fully specified up front.\n\n\n\n### Arguments\n\n\n`WEBSERVICE(url)`\n\n- **`url`** (required) — Microsoft: \"The URL of the web service to be called\".\n\nThe argument's admissible values are bounded by three documented limits at once: at most 2,048\ncharacters (the GET limit), a supported protocol, and a result that fits in a cell. The\nmisunderstanding worth naming is that `url` is not a template — there is no separate parameter\nlist, so query parameters are built by concatenation, and any value interpolated into the URL\nmust be percent-encoded first. Microsoft says so directly: \"For the best results, the URL for\nWEBSERVICE should be encoded prior to inclusion in the formula\", pointing at `ENCODEURL`.\n\n" }, "signature": { "display": "WEBSERVICE(url)", "parameters": [ { "description": null, "name": "url", "optional": false, "repeats": false } ], "trailing_repeats": false }, "sources": { "metadata": { "admission": { "label": "not_implemented", "reason": "No catalogue row at this commit. WEBSERVICE fetches from the URL in the workbook, not from a Microsoft back end, and is being implemented as an ordinary function." }, "arity": { "max": 1, "min": 1 }, "category": "Web functions", "classification": {}, "descriptions": { "long": null, "short": "Text fetched from a web service at a URL", "short_source": "dna-calc-own" }, "docs": { "english_description": "Returns data from a web service", "microsoft_url": "https://support.microsoft.com/en-us/office/webservice-function-0546a35a-ecc6-4739-aed7-c0b7ce1562c4" }, "entry_kind": "built_in_function", "localized_family_names": null, "localized_names": [ { "locale": "ar-SA", "name": "WEBSERVICE" }, { "locale": "bg-BG", "name": "WEBSERVICE" }, { "locale": "cs-CZ", "name": "WEBSERVICE" }, { "locale": "da-DK", "name": "WEBTJENESTE" }, { "locale": "de-DE", "name": "WEBSERVICE" }, { "locale": "el-GR", "name": "WEBSERVICE" }, { "locale": "en-AU", "name": "WEBSERVICE" }, { "locale": "en-GB", "name": "WEBSERVICE" }, { "locale": "en-US", "name": "WEBSERVICE" }, { "locale": "es-ES", "name": "SERVICIOWEB" }, { "locale": "et-EE", "name": "WEBSERVICE" }, { "locale": "fi-FI", "name": "VERKKOPALVELU" }, { "locale": "fr-FR", "name": "SERVICEWEB*" }, { "locale": "he-IL", "name": "WEBSERVICE" }, { "locale": "hr-HR", "name": "WEBSERVICE" }, { "locale": "hu-HU", "name": "WEBSZOLGÁLTATÁS" }, { "locale": "id-ID", "name": "WEBSERVICE" }, { "locale": "it-IT", "name": "WEBSERVICE" }, { "locale": "ja-JP", "name": "WEBSERVICE" }, { "locale": "ko-KR", "name": "WEBSERVICE" }, { "locale": "lt-LT", "name": "WEBSERVICE" }, { "locale": "lv-LV", "name": "WEBSERVICE" }, { "locale": "nb-NO", "name": "WEBSERVICE" }, { "locale": "nl-NL", "name": "WEBSERVICE" }, { "locale": "pl-PL", "name": "WEBSERVICE" }, { "locale": "pt-BR", "name": "WEBSERVICE" }, { "locale": "pt-PT", "name": "SERVIÇOWEB" }, { "locale": "ro-RO", "name": "WEBSERVICE" }, { "locale": "ru-RU", "name": "ВЕБСЛУЖБА" }, { "locale": "sk-SK", "name": "WEBSERVICE" }, { "locale": "sl-SI", "name": "WEBSERVICE" }, { "locale": "sr-Latn-RS", "name": "WEBSERVICE" }, { "locale": "sv-SE", "name": "WEBBTJÄNST" }, { "locale": "th-TH", "name": "WEBSERVICE" }, { "locale": "tr-TR", "name": "WEBHİZMETİ" }, { "locale": "uk-UA", "name": "WEBSERVICE" }, { "locale": "vi-VN", "name": "WEBSERVICE" }, { "locale": "zh-CN", "name": "WEBSERVICE" }, { "locale": "zh-HK", "name": "WEBSERVICE" }, { "locale": "zh-TW", "name": "WEBSERVICE" } ], "signature": { "display": "WEBSERVICE(url)", "parameters": [ { "description": null, "name": "url", "optional": false, "repeats": false } ], "trailing_repeats": false }, "surface_name": "WEBSERVICE", "version_marker": null, "xlcall": { "code": "596", "symbol": "xlfWebservice" } }, "microsoft": "https://support.microsoft.com/en-us/office/webservice-function-0546a35a-ecc6-4739-aed7-c0b7ce1562c4" }, "try_it": { "formula": "=WEBSERVICE(\"https://example.com/data\")", "note": "This example needs an Excel service or external provider that OneCalc cannot supply in this preview.", "preview_status": "refused" }, "url": "https://handbook.dnacalc.com/functions/WEBSERVICE.html", "variants": [], "versions": [] }