Enhanced Query Parameters in the Babylon API

By Gary Kennedy
October 15, 2025

Every API begins simply. A few clean endpoints, a handful of query parameters — ?symbol=AAPL, ?date=2025-09-01 — and everything feels elegant. Then the real world arrives. You need to exclude certain accounts, filter by date ranges, or select everything except one value. Suddenly that neat equality model starts to creak.

At Babylon, we wanted a way to keep the simplicity of field=value while still expressing richer intent. Something compact enough for a URL, yet powerful enough for many real-world cases.

Most of the time, a regular query parameter is enough:

GET /analysis/position?ledgerId=MyUKLedger&currency=GBP

That’s the standard pattern everyone knows: field=value means equality. But what if you need to ask for “everything except SIPP accounts,” or “transactions settled on or before a certain date”? Plain equality just isn’t enough and yet these parmeters are known as query parameters.

This is where our Colon Operator Query Parameters come in.

The Idea: Colon Operator Query Parameters

Enhanced query parameters extend the familiar field=value pattern by allowing simple operators inside the value. Equality remains the default:

asOfDate=2025-09-01 → asOfDate equals 2025-09-01

Other operators are prefixed before the value:

asOfDate=lte:2025-09-01 → asOfDate less than or equal to 2025-09-01
accountType=nin:SIPP+ISA → accountType is not in the list (SIPP, ISA)

We call this the Colon Operator style because the operator comes before a colon in the value. This way we preserve the field name and extend only the value.

Supported Operators

For now we support a small, easy-to-learn set:

Example 1: Excluding Tax-Free Accounts

When calculating tax-related metrics, pension and tax-free accounts (-SIPP, -ISA) are typically excluded. Instead of inventing a special excludeTypes parameter where the specific operator (exclude) is explicitly hardcoded in the parameter name, you can now use enhanced filtering directly:

GET /analysis/capital-gains?ledgerId=MyUKLedger&accountType=nin:SIPP+ISA

This returns all accounts except those of type SIPP or ISA. The API stays compact and the intent is obvious.

Example 2: Settled Transactions by Date

Another common need is tax-jurisdiction change: you want only transactions settled on or before a cut-off date. With enhanced query parameters you can express this cleanly:

GET /ledgers?ledgerId=MyZALedger&settleDate=lte:2025-09-01

This selects transactions settled on or before 1 September 2025, without adding any new, special-purpose query parameter.

How Our Approach Compares

We’re not the first to face this problem — several well-known APIs already allow richer filtering:

• Stripe uses bracket operators on the field name:
  amount[gt]=100&created[lte]=2025-09-01
• OData and Google Cloud APIs use a single $filter expression:
  $filter=amount gt 100 and date le 2025-09-01
• RSQL uses symbolic operators in a query language:
  filter=amount=gt=100;date=le=2025-09-01

All of these approaches solve the same problem. But they do it by either modifying the field name (e.g. amount[gt]) or introducing a special filter parameter (filter=...).

At Babylon, we preferred to keep the field name intact and enrich the value side instead:

amount=gt:100
date=lte:2025-09-01

We found that this makes URLs more natural to read (in our opinion), less error-prone to write, and easier to explain: “it’s just a query parameter, with an operator before the value.”

Why This Matters

Enhanced query parameters give you:

• Clarity: the URL tells the story without extra documentation.
• Simplicity: equality is still just field=value, no extra syntax needed.
• Consistency: the same operator set works across dates, numbers, and strings.
• Continuity: we preserve the normal query parameter model, extending rather than replacing it.

It’s a small change, but it makes the Babylon API more expressive while staying true to the web’s original query parameter design.

What’s Next

Over time, we may add more operators, most likely string functions such as (startsWith, nstartsWith, endsWith, nendsWith, contains, ncontains) as real use cases demand. But the principle will stay the same: colon operators inside values, field names untouched.

Should we require must richer queries, then either query endpoint (/ledgers/{ledgerId}/filter) or an explicit filter field with a value rich in structure or both.