{"id":2301,"date":"2026-09-11T07:27:39","date_gmt":"2026-09-10T23:27:39","guid":{"rendered":"https:\/\/xlwings.net\/blog\/?p=2301"},"modified":"2026-03-28T12:41:51","modified_gmt":"2026-03-28T12:41:51","slug":"how-to-use-worksheetxmlmapquery-in-the-xlwings-api-way","status":"publish","type":"post","link":"https:\/\/xlwings.net\/blog\/how-to-use-worksheetxmlmapquery-in-the-xlwings-api-way\/","title":{"rendered":"How to use Worksheet.XmlMapQuery in the xlwings API way"},"content":{"rendered":"\n

The XmlMapQuery<\/code> member of the Worksheet<\/code> object in the Excel object model provides a powerful interface for querying and retrieving data from XML maps that have been added to a workbook. In xlwings, this functionality is accessible through the api<\/code> property, allowing Python scripts to interact directly with Excel’s underlying COM objects. This is particularly useful for extracting structured data from XML sources mapped into Excel worksheets, enabling automation of data retrieval and integration tasks.<\/p>\n\n\n\n

Functionality:<\/strong>
The XmlMapQuery<\/code> method executes a query against an XML map associated with the worksheet, returning a Range<\/code> object that represents the cells containing the queried data. It allows you to specify XPath expressions to filter or select specific nodes from the XML data, making it possible to import only relevant subsets into Excel. This is essential for handling large or complex XML datasets where selective data extraction is needed for analysis or reporting.<\/p>\n\n\n\n

Syntax in xlwings:<\/strong>
In xlwings, you call this member via the api<\/code> property of a Worksheet<\/code> object. The general syntax is:<\/p>\n\n\n\n

worksheet.api.XmlMapQuery(XPath, SelectionNamespaces, Map)<\/code><\/pre>\n\n\n\n
    \n
  • XPath<\/strong>: A string specifying the XPath expression to query the XML map. This determines which data nodes are retrieved. For example, \"\/root\/element\"<\/code> selects all element<\/code> nodes under the root<\/code>.<\/li>\n\n\n\n
  • SelectionNamespaces<\/strong>: A string containing the namespace declarations required for the XPath query, if the XML uses namespaces. It should be formatted as a space-separated list of xmlns:prefix=\"URI\"<\/code> declarations. For instance, 'xmlns:ns=\"http:\/\/example.com\"'<\/code>.<\/li>\n\n\n\n
  • Map<\/strong>: An optional parameter that specifies the XmlMap<\/code> object to query. If omitted, Excel uses the first XML map in the workbook. You can pass an XmlMap<\/code> object retrieved via the workbook’s XmlMaps<\/code> collection.<\/li>\n<\/ul>\n\n\n\n
    Example Usage:<\/strong>
    Suppose you have an XML map in an Excel workbook linked to a worksheet, and you want to query data from it using xlwings. Below is a code example that demonstrates how to use XmlMapQuery<\/code> to retrieve specific data:<\/p>\n\n\n\n
    import xlwings as xw\n\n# Connect to the open Excel workbook and worksheet\napp = xw.apps.active\nwb = app.books.active\nws = wb.sheets['Sheet1']\n\n# Define the XPath query and namespaces (if needed)\nxpath_expression = \"\/Orders\/Order[Status='Shipped']\"\nnamespaces = 'xmlns:ord=\"http:\/\/www.example.com\/orders\"'\n\n# Execute the XML map query\n# Assuming the first XML map in the workbook is used\nresult_range = ws.api.XmlMapQuery(xpath_expression, namespaces)\n\n# Check if data was returned and output it\nif result_range:\n    # Convert the range to a list of lists for easy processing in Python\n    data = result_range.value\n    print(\"Queried Data:\", data)\n    # You can now analyze or visualize this data using Python libraries\nelse:\n    print(\"No data found for the query.\")\n\n# Alternatively, specify a particular XML map by name\nxml_map = wb.api.XmlMaps(\"MyXmlMap\") # Replace with your map name\nresult_range_specific = ws.api.XmlMapQuery(xpath_expression, namespaces, xml_map)<\/code><\/pre>\n\n\n\n
    <\/p>\n","protected":false},"excerpt":{"rendered":"
    The `XmlMapQuery` member of the `Worksheet` object in the Excel object model provides a powerful int…<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[25],"tags":[],"class_list":["post-2301","post","type-post","status-publish","format-standard","hentry","category-xlwings-api-reference"],"_links":{"self":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2301","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/comments?post=2301"}],"version-history":[{"count":1,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2301\/revisions"}],"predecessor-version":[{"id":3509,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/posts\/2301\/revisions\/3509"}],"wp:attachment":[{"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/media?parent=2301"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/categories?post=2301"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/xlwings.net\/blog\/wp-json\/wp\/v2\/tags?post=2301"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}