OmniCommerce Developer Docs

Catalog & GEO API

OpenAPI JSON: https://omnicommerce.sg/openapi.json

Quick Start

1) Search catalog

curl -sS "https://omnicommerce.sg/api/catalog?q=fan&platform=lazada&country=sg&language=en&limit=5"

/api/catalog is public and returns globally discoverable active products.

2) Match GEO intent

curl -sS -X POST "https://omnicommerce.sg/api/geo/match" \
  -H "Content-Type: application/json" \
  -d '{"query":"humid weather fan","platform":"lazada","country":"sg","language":"en","limit":5,"includeCatalog":true}'

GEO endpoints are also public for agent and crawler access.

MCP Endpoint

MCP JSON-RPC endpoint: https://omnicommerce.sg/api/mcp

Full MCP docs: https://omnicommerce.sg/docs/mcp

Exposed tools: omni_search_catalog, omni_match_intent, omni_discover_geo, omni_geo_feed

Initialize MCP

curl -sS -X POST "https://omnicommerce.sg/api/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"agent","version":"1.0.0"}}}'

Call omni_search_catalog via MCP

curl -sS -X POST "https://omnicommerce.sg/api/mcp" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"omni_search_catalog","arguments":{"q":"fan","platform":"lazada","country":"sg","language":"en","limit":5}}}'

Endpoints

/api/catalog

GETSearch Catalog Products

Search public catalog products and return structured product + GEO fields for agent and tool usage.

Parameters

Name	In	Required	Type	Description	Rules
q	query	no	string	Free-text query (max 300 chars).	maxLength 300
platform	query	no	shopee \| lazada	Marketplace platform filter.	-
country	query	no	string	Country code hint (example: sg). Used for localization/signal preference, not strict exclusion.	-
language	query	no	en \| th \| id \| ms \| vi \| tl	Localization language. Defaults to en.	default en
minGeoScore	query	no	integer	Minimum GEO readiness score (0..100).	min 0, max 100
limit	query	no	integer	Result limit (1..100). Defaults to 20.	min 1, max 100, default 20
offset	query	no	integer	Pagination offset (0..10000). Defaults to 0.	min 0, max 10000, default 0

Response Codes

200, 400, 500

/api/geo/discover

POSTDiscover GEO Matches

Canonical embedding-based GEO retrieval endpoint with deterministic ranking over public catalog content.

JSON Body Fields

Field	Required	Type	Description	Rules
query	yes	string	Intent query text.	-
platform	no	shopee \| lazada	-	-
country	no	string	-	-
language	no	en \| th \| id \| ms \| vi \| tl	-	default en
limit	no	integer	-	min 1, max 50, default 20
minScore	no	integer	-	min 0, max 100, default 0
minSimilarity	no	number	-	min 0, max 1, default 0.35

Response Codes

200, 400, 401, 402, 403, 500

/api/geo/feed

GETList GEO Feed

List GEO-enriched public catalog entries with marketplace links and localization metadata.

Parameters

Name	In	Required	Type	Description	Rules
platform	query	no	shopee \| lazada	Marketplace platform filter.	-
country	query	no	string	Country code hint (example: sg). Used for localization/signal preference, not strict exclusion.	-
language	query	no	en \| th \| id \| ms \| vi \| tl	Localization language. Defaults to en.	default en
limit	query	no	integer	Result limit (1..200). Defaults to 100.	min 1, max 200, default 100

Response Codes

200, 400, 401, 402, 403, 500

/api/geo/match

GETMatch GEO Intent (GET)

Query-string GEO matching endpoint. Thin wrapper over discover with optional catalog hydration.

Parameters

Name	In	Required	Type	Description	Rules
q	query	no	string	Intent query text alias for query.	-
query	query	no	string	Intent query text.	-
platform	query	no	shopee \| lazada	Marketplace platform filter.	-
country	query	no	string	Country code hint (example: sg). Used for localization/signal preference, not strict exclusion.	-
language	query	no	en \| th \| id \| ms \| vi \| tl	Localization language. Defaults to en.	default en
limit	query	no	integer	Result limit (1..50). Defaults to 20.	min 1, max 50, default 20
minScore	query	no	integer	Minimum GEO readiness score (0..100).	min 0, max 100, default 0
minSimilarity	query	no	number	Minimum semantic similarity (0..1).	min 0, max 1, default 0.35
includeCatalog	query	no	boolean	Include hydrated catalog object per match. Defaults to true.	default true
include_catalog	query	no	boolean	Legacy alias for includeCatalog. (deprecated)	default true

Response Codes

200, 400, 401, 402, 403, 500

POSTMatch GEO Intent (POST)

JSON-body GEO matching endpoint for function-calling and MCP tool usage.

JSON Body Fields

Field	Required	Type	Description	Rules
query	yes	string	Intent query text.	-
platform	no	shopee \| lazada	-	-
country	no	string	-	-
language	no	en \| th \| id \| ms \| vi \| tl	-	default en
limit	no	integer	-	min 1, max 50, default 20
minScore	no	integer	-	min 0, max 100, default 0
minSimilarity	no	number	-	min 0, max 1, default 0.35
includeCatalog	no	boolean	-	default true

Response Codes

200, 400, 401, 402, 403, 500