Search games

Search for games in the Microsoft Store.

Response Structure:

• content: Search results with matching games
• code: HTTP status code from upstream

Market and device family

market and deviceFamily are optional and default to US and Windows.Desktop - omit them and behaviour is unchanged.

Both affect results. deviceFamily=Windows.Xbox drops PC-only entries such as demos; market changes both availability and ordering.

Note: locale comes from your account setting, while market defaults to US regardless. If your account locale is, say, hu-HU, the default request is market=US&locale=hu-HU - a mismatched pair that measurably worsens result relevance. If your account locale is not US English, pass a matching market (e.g. ?market=HU). The default is left as US so existing integrations do not shift underneath them.

Pagination

Responses include Payload.NextUri, which contains a cursor query parameter. Extract that cursor value and pass it back to get the next page, keeping your other parameters identical:

GET /v2/marketplace/search?q=halo
GET /v2/marketplace/search?q=halo&cursor=bz0wJmI9OU5WM0wyMzRWR1hE...

Pass only the cursor value, not the whole NextUri.

Keep following NextUri until it stops coming back. Two things to be aware of on cursor pages:

• FilterOptions is returned on the first page only, so treat it as optional.
• Per-product fields that depend on promotions (StrikethroughPrice, SubscriptionDiscountMessageTemplate, SkusSummary[].IncludedWith) appear only for products that are on sale or included with a subscription. They are absent otherwise on any page - do not rely on them being present.

Result relevance

This endpoint is backed by the Microsoft Store search, which always returns roughly 20 cards and pads the tail with recommendations once it runs out of genuine matches. A search for a game with few close matches will return mostly unrelated titles, and the upstream exposes no relevance score to filter on.

If you want strict matching, use GET /v2/marketplace/autosuggest, which matches on title and returns only real matches.

Getting title IDs

Search results carry a ProductId, not an Xbox title ID. Pass enrich=titleid to attach an XboxTitleId field to every result:

GET /v2/marketplace/search?q=halo&enrich=titleid

XboxTitleId is null for products that genuinely have none - add-ons, bundles and some PC-only listings. In a typical 20-result page around 16 resolve and 4 come back null. This also makes it possible to tell apart two listings of the same game that are otherwise identical by title.

The field is only present when you ask for it. Without enrich=titleid the response has no XboxTitleId key at all, which keeps the default response byte-for-byte what it was before.

Enrichment costs an additional upstream catalog lookup, so it is off by default.