A full traversal

When using Search Actions, the resulting items are divided into pages. To retrieve additional pages of result items, it is necessary to extract the “NextPage” api:Continuation elements and include them in a subsequent api:ApiRequest to the primary API endpoint.

Since api:Continuation elements belong to the api:AbstractAction substitution group, these elements can be directly transferred from the api:ApiResponse to the following api:ApiRequest.

AbstractAction

Important

When executing bulk operations such as full traversals, be aware of your Response Data Transfer Quota consumption. Ensure your client applications are designed to adhere to the Retry-After Header if the API service signals that a pause is necessary.

Initial Requests for Full Traversals

To execute a full traversal of the database, create an initial query that retrieves all items containing the LastUpdate field. Since this field is present in each data item, this query yields all possible items.

  <Page size="64"/>
  <Query>
    <LastUpdate/>
  </Query>
  <Sort>
    <LastUpdateSort>Ascending</LastUpdateSort>
  </Sort>

Tip

For optimal results, request an Ascending sort order on the LastUpdate field by including the LastUpdateSort element in your sorting criteria.

Be aware that if the underlying database is updated during the traversal, items may reappear in subsequent result pages when traversing in ascending order. Conversely, if you traverse in descending order, any item updated after the traversal begins might be omitted from all result pages.

Trademark Search full traversal request

This is an example request to start a full traversal for Trademark Search:

<?xml version="1.0"?>
<ApiRequest xmlns="urn:ige:schema:xsd:datadeliverycore-1.0.0" xmlns:tmk="urn:ige:schema:xsd:datadeliverytrademark-1.0.0">
  <Action type="TrademarkSearch">
    <tmk:TrademarkSearchRequest xmlns="urn:ige:schema:xsd:datadeliverycommon-1.0.0">
      <Page size="64"/>
      <Query>
        <LastUpdate/>
      </Query>
      <Sort>
        <LastUpdateSort>Ascending</LastUpdateSort>
      </Sort>
    </tmk:TrademarkSearchRequest>
  </Action>
</ApiRequest>

Patent Search full traversal request

This is an example request to start a full traversal for Patent Search:

<?xml version="1.0"?>
<ApiRequest xmlns="urn:ige:schema:xsd:datadeliverycore-1.0.0" xmlns:pat="urn:ige:schema:xsd:datadeliverypatent-1.0.0">
  <Action type="PatentSearch">
    <pat:PatentSearchRequest xmlns="urn:ige:schema:xsd:datadeliverycommon-1.0.0">
      <Page size="64"/>
      <Query>
        <LastUpdate/>
      </Query>
      <Sort>
        <LastUpdateSort>Ascending</LastUpdateSort>
      </Sort>
    </pat:PatentSearchRequest>
  </Action>
</ApiRequest>

Locating Continuation Elements

If present, the api:Continuation elements are nested within the api:Continuations wrapper element of the api:Result element.

Result Continuations Continuation

The Meta Element

The api:Meta element provides information about the current state of the traversal:

<api:Meta>
  <db:TotalItemCount xmlns:db="urn:ige:schema:xsd:datadeliverycommon-1.0.0">27707</db:TotalItemCount>
  <db:ItemCountOffset xmlns:db="urn:ige:schema:xsd:datadeliverycommon-1.0.0">0</db:ItemCountOffset>
  <db:ItemCount xmlns:db="urn:ige:schema:xsd:datadeliverycommon-1.0.0">64</db:ItemCount>
</api:Meta>

  • TotalItemCount: This element indicates the total number of items available across all pages. In the example above, there are 27707 items in total.

  • ItemCountOffset: This element specifies the offset of the first item on the current page. An offset of 0 means that the current page begins with the first item in the set.

  • ItemCount: This element represents the number of items returned on the current page. In this case, there are 64 items on the current page.

Constructing the Follow-up Request

To effectively traverse through additional pages of results, it is crucial to correctly assemble the follow-up api:ApiRequest.

The code snippet below demonstrates how to extract the continuations and construct the follow-up request:

Python: full_traversal.py
 1#!/usr/bin/env python3
 2from typing import Optional, Tuple, List
 3import xml.etree.ElementTree as ET
 4from copy import deepcopy
 5
 6namespaces = {
 7    'api': 'urn:ige:schema:xsd:datadeliverycore-1.0.0',
 8    'db': 'urn:ige:schema:xsd:datadeliverycommon-1.0.0'
 9}
10
11def api_followup_request(root: ET.Element, *continuation_names: str) -> Optional[Tuple[str, List[int]]]:
12    """
13    Extracts continuation elements from each api:Result element in an API response XML tree.
14    Only those continuations matching the provided 'continuation_names' (or all if none provided)
15    are included in a global ApiRequest XML element. This function also returns the indices (zero‐based)
16    of the api:Result elements that contributed at least one matching continuation.
17    
18    Args:
19        root: The root XML element of the API response.
20        *continuation_names: Optional names of continuations (e.g., "NextPage") to filter by.
21        
22    Returns:
23        A tuple where:
24          - the first element is a string representation of the combined ApiRequest XML containing matching continuations,
25          - the second element is a list of integers representing the indices of api:Result elements that contributed.
26        Returns None if no matching continuation is found.
27    """
28    followup = ET.Element('ApiRequest', {'xmlns': namespaces['api']})
29    indices: List[int] = []
30
31    result_elements = root.findall('./api:Result', namespaces)
32    for idx, result_elem in enumerate(result_elements):
33        continuation_elements = result_elem.findall('./api:Continuations/api:Continuation', namespaces)
34        added_from_this_result = False
35
36        for cont in continuation_elements:
37            cont_name = cont.attrib.get('name')
38            if not continuation_names or (cont_name in continuation_names):
39                followup.append(deepcopy(cont))
40                added_from_this_result = True
41        
42        if added_from_this_result:
43            indices.append(idx)
44
45    if not indices:
46        return None
47    
48    followup_xml = ET.tostring(followup, encoding='unicode')
49    return followup_xml, indices
50
51
52if __name__ == '__main__':
53    api_response_xml = """<?xml version="1.0" encoding="UTF-8"?>
54    <api:ApiResponse xmlns:api="urn:ige:schema:xsd:datadeliverycore-1.0.0">
55      <api:Result success="true">
56        <!-- ... -->
57        <api:Continuations>
58          <api:Continuation name="NextPage">QUVTL0dDTS9Ob1BhZGRpbmcAR0NN...</api:Continuation>
59        </api:Continuations>
60      </api:Result>
61      <api:Result success="true">
62        <!-- ... -->
63        <api:Continuations>
64          <api:Continuation name="SomeThingElse">QUVTL0dDTS9Ob1BhZGRpbmcAR0NN...</api:Continuation>
65        </api:Continuations>
66      </api:Result>
67    </api:ApiResponse>
68    """
69
70    result = api_followup_request(ET.fromstring(api_response_xml), "NextPage")
71    if result:
72        followup_xml, indices = result
73        print("Follow-up ApiRequest XML:")
74        print(followup_xml)
75        print("Contributing result indices:")
76        print(indices)
77    else:
78        print("No matching continuations found.")