Query conventions

Query conventions

These conventions are identical across every endpoint. Learn them once.

Pagination

?page=N&pageSize=M

• page is 1-indexed (the first page is page=1).
• pageSize defaults to 50 and maxes out at 500.
• If you request pageSize above 500, the server silently clamps it to 500 and sets the response header Sedis-Page-Size-Clamped: true. You still get a 200 — just check the header if you care.

The envelope tells you where you are:

{ "data": [ ... ], "page": 2, "pageSize": 50, "totalCount": 142, "totalPages": 3 }

Opting out of the count

Computing totalCount costs an extra COUNT(*) query. On the high-volume /fastighetsbenchmark/comp-data endpoint you can skip it for bulk sync:

?count=false

Then totalCount and totalPages come back null and you page until data is empty.

Sorting

?sort=field,-field

• Comma-separated list of fields.
• A leading - means descending.
• Sort fields are whitelisted per endpoint. An unknown field returns a 400 (Errors (RFC 7807)) naming the offender.
• Each endpoint has a stable default sort (typically primary key ascending) so paging is consistent.

Example — companies by name descending:

curl -H "X-Api-Key: $SEDIS_API_KEY" \
  "https://api.sedis.se/v2/bolagsanalys/companies?sort=-name"

Sparse fieldsets

?fields=a,b,c

Returns only the listed fields (a flat comma list — no nested syntax). An unknown field name returns a 400 naming it. Use this to:

• Trim payloads (and tokens, if you're feeding an LLM).
• Opt into otherwise-omitted fields. On Fastighetsbenchmark, geometry, belongsToJamforelseobjekt, containsPropertyUnits (Jämförelseobjekt only), and tags are omitted by default and only appear when you ask for them:

curl -H "X-Api-Key: $SEDIS_API_KEY" \
  "https://api.sedis.se/v2/fastighetsbenchmark/property-units?fields=sedisId,name,geometry"

See Geometry and The Comp Composite & clone lineage for the opt-in fields.

Named filters

v2 uses named query parameters per endpoint, not a generic filter language. Each endpoint documents its own filters (Endpoints reference).

Multi-value matching on ID filters uses a dedicated <field>In parameter that takes a comma-separated list of values — there is no in: value-prefix operator. For example, ?sedisId= matches one id exactly, while ?sedisIdIn= matches any id in the list:

?sedisIdIn=PU-1,PU-2,PU-3

Conditional requests (ETags / If-None-Match)

GET responses carry a weak ETag. Send it back on your next request and if nothing changed you get a 304 Not Modified with no body — saving bandwidth and not counting against your data transfer.

# First call — note the ETag header
curl -i -H "X-Api-Key: $SEDIS_API_KEY" \
  "https://api.sedis.se/v2/fastighetsbenchmark/property-units?sedisId=PU-1"
# → ETag: W/"lastUpdated-1735689600"

# Follow-up — send it back
curl -i -H "X-Api-Key: $SEDIS_API_KEY" \
  -H 'If-None-Match: W/"lastUpdated-1735689600"' \
  "https://api.sedis.se/v2/fastighetsbenchmark/property-units?sedisId=PU-1"
# → HTTP/1.1 304 Not Modified  (no body)

• Single-resource ETags derive from the resource's lastUpdatedUtc.
• List ETags derive from (query string, max lastUpdatedUtc in the page, totalCount) — any change to the result set invalidates them.
• POST /search responses are not cached (Cache-Control: no-store, no ETag).

How ETags relate to data freshness is covered in Data freshness.

Response compression

From the Sedis release in late September 2026, JSON responses are compressed when your client asks for it — Brotli (br) if you accept it, otherwise gzip. This applies to both v2 and the v1 OData API. Large result sets shrink to roughly a tenth of their size: a 19 MB v1 response arrives as about 2 MB.

• Nothing to opt into, nothing breaks. Compression happens only when the request carries Accept-Encoding: br or gzip. A client that sends no Accept-Encoding gets exactly the same bytes as before, and the decompressed body is always identical to the uncompressed one.
• Compressed responses carry Content-Encoding: br (or gzip) and Vary: Accept-Encoding.
• Most clients already ask for it and decompress transparently: Python requests, R httr/httr2, Power Query, browsers, and Node's fetch (which @sedis/mcp uses).
• .NET HttpClient does not by default. Enable it on the handler — see the C# block in Code examples:

var http = new HttpClient(new HttpClientHandler { AutomaticDecompression = DecompressionMethods.All });

• curl needs --compressed, which both sends the header and decompresses the body.

Compression cuts transfer time; it does not make the server assemble a result faster. For large pulls, requesting only what you need (?fields=, filters, paging) still matters most.