Generate your first evaluator

First install the CLI. This walkthrough uses a local description, so no running search service is needed.

1. Save a description

Create opensearch.xml:

<?xml version="1.0" encoding="UTF-8"?>
<OpenSearchDescription xmlns="http://a9.com/-/spec/opensearch/1.1/">
  <ShortName>Example search</ShortName>
  <Description>Example search service</Description>
  <Tags>example search</Tags>
  <Url type="application/json"
       template="https://example.test/search?q={searchTerms}&amp;limit={count?}&amp;format=json"/>
</OpenSearchDescription>

searchTerms is required, count is optional, and format=json is fixed. The XML uses &amp; to separate query parameters.

2. Generate the module

osdd2pygeofilter opensearch.xml --output search_evaluator.py

The command writes search_evaluator.py. Choose an output filename that is a valid Python module name. Existing output is replaced.

3. Convert a filter

Save the following as search_example.py beside the generated file:

from search_evaluator import from_cql2_text

query = from_cql2_text("searchTerms = 'ocean & ice' AND count = 10")
print(query)

Run it in the same Python environment:

python search_example.py

Output:

{'q': 'ocean & ice', 'limit': '10'}

CQL2 property names match template placeholders: searchTerms maps to q, and count maps to limit. The dictionary contains decoded filter values. To validate the complete query and call the service, use the generated helper:

from search_evaluator import invoke

response = invoke(query)

This merges defaults with filter values, validates them, expands the original URL template (preserving fixed values such as format=json), and makes an HTTP GET (the default when no method is declared). Parameters with advertised options log a warning during conversion when their value is not listed; options are suggestions, so this warning does not prevent the request.

Next, learn about remote sources and authentication and which queries are supported.

For a complete live-service example, continue with Search EUMETSAT products with CQL2.