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}&limit={count?}&format=json"/>
</OpenSearchDescription>
searchTerms is required, count is optional, and format=json is fixed.
The XML uses & 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.