Search API

Reference for the Glood Hydrogen Search v1 surface. For a guided walkthrough, see Search & Discovery.

All search calls are v1 on the search host (https://search.glood.ai) and authenticate with Authorization: Bearer <apiKey> + x-shop. Params are camelCase (mapped to snake_case on the wire); responses are snake_case exactly as returned by the backend.

Hooks

React hooks, each usable within a <GloodProvider> whose client has the search app registered (.use(search())).

useSearch()

Runs a full product search for the current params and exposes attribution helpers.

function useSearch(
  params: SearchParams,
  options?: { skip?: boolean }
): UseSearchResult

Parameters — params is a SearchParams (all optional; query may be ""). options.skip (default false) holds fetching until required params are ready. Returns — UseSearchResult

Attribute	Type	Description
`products`	`SearchItem[]`	Result products (or `{ product_id }` refs when `view: 'product_ids'`). Empty while loading
`data`	`SearchResponse \| null`	Full response (`request_id`, `pagination`, `facets`, `metadata`)
`loading`	`boolean`	`true` while in flight
`error`	`Error \| null`	`GloodApiError` on API failures
`refetch`	`() => void`	Re-run with the same params
`trackSearch`	`(track: SearchTrack) => void`	Emit `glood:instant_search_triggered`
`trackResultView`	`(track: SearchTrack) => void`	Emit `glood:search_result_rendered`
`trackResultClick`	`(track: SearchTrack) => void`	Emit `glood:search_result_clicked`
`trackAddToCart`	`(track: SearchTrack) => void`	Emit `glood:search:add_to_cart`
`trackFilter`	`(track: SearchTrack) => void`	Emit `glood:search_filter_updated`

const { products, data, trackResultClick } = useSearch({
  query: 'running shoe',
  sort: 'price_asc',
  facets: [{ key: 'color', operator: 'or', value: ['red'] }],
  pagination: { page: 1, limit: 24 },
  options: { includeFacets: true, personalize: true },
});

useInstantSearch()

Type-ahead search. On an empty / too-short query the response carries trending.

function useInstantSearch(
  params: InstantSearchParams,
  options?: { skip?: boolean }
): UseInstantSearchResult

Parameters — params is an InstantSearchParams (query required, may be ""). Use options.skip to gate on the minimum query length. Returns — UseInstantSearchResult

Attribute	Type	Description
`data`	`InstantSearchResponse \| null`	Full response (products, suggestions, autocorrect, trending)
`products`	`SearchItem[]`	Convenience: `data.products.results`
`suggestions`	`SearchSuggestion[]`	Convenience: keyword suggestions
`collections`	`InstantSearchCollection[]`	Convenience: collection results
`pages`	`InstantSearchPage[]`	Convenience: page results
`loading`	`boolean`	`true` while in flight
`error`	`Error \| null`	Error, if any
`refetch`	`() => void`	Re-run with the same params

const { products, suggestions, data } = useInstantSearch(
  { query: term, objects: ['product', 'query_suggestion', 'autocorrect'] },
  { skip: term.length < 2 },
);

useSearchConfig()

Fetches the headless search config (feature flags, filter definitions, shop, analytics, translations, storefront token).

function useSearchConfig(
  params?: SearchConfigParams,
  options?: { skip?: boolean }
): UseSearchConfigResult

Returns — UseSearchConfigResult: { config: SearchConfigResponse | null, loading, error, refetch }.

const { config } = useSearchConfig({ locale: 'en-US' });

useSearchInit() / useSearchInitReady()

GloodProvider runs the search session bootstrap once on mount (when search() is registered), mirroring recs init. You don’t call it yourself — these hooks read its result:

function useSearchInit(): SearchInitResponse | null
function useSearchInitReady(): boolean

useSearchInit() returns the SearchInitResponse (visitor identity, history, lean config, token, visit_id), or null until it resolves.
useSearchInitReady() returns true once init has settled (success or failure). useSearch and useInstantSearch gate their fetches on this, so they don’t fire before the session is bootstrapped.

const init = useSearchInit();
const ready = useSearchInitReady();
// init?.visitor.browsed_products, init?.token, init?.visit_id …

Standalone functions

Isomorphic functions for the v1 search suite. Use them in Hydrogen route loaders (SSR) or anywhere you need the API without a React component. Every function takes options: FetchSearchOptions as its first argument.

Endpoints

Each function POSTs to a path under the search endpoint (default https://search.glood.ai), all v1:

Function	Method + Path
`fetchSearchInit(options, params?)`	`POST /api/storefront/v1/headless/init`
`fetchSearchConfig(options, params?)`	`POST /api/storefront/v1/headless/config`
`fetchInstantSearch(options, params)`	`POST /api/storefront/v1/headless/instant-search`
`fetchFilters(options, params?)`	`POST /api/storefront/v1/headless/filters`
`fetchFilterAggregations(options, params?)`	`POST /api/storefront/v1/headless/filter-aggregations`
`fetchSearchResults(options, params?)`	`POST /api/storefront/v1/headless/search`
`fetchImageSearch(options, params)`	`POST /api/storefront/v1/headless/image-search`
`sendSearchEvent(options, params)`	`POST /api/storefront/v1/headless/events`

FetchSearchOptions is the shared HeadlessRequestOptions — apiKey and myShopifyDomain are required; endpoint (default https://search.glood.ai) and debug are optional. The version is pinned to 1 internally. In the browser, visitor_id / client_id / session_id default from the Glood cookies when omitted.

The standalone functions above POST to whatever endpoint you pass in options. When you call through the SearchApp (app.imageSearch(...), the track* helpers, auto-subscribed events), routing is split automatically: imageSearch and all events go to the app’s controlEndpoint (non-edge), while every other call uses endpoint. See Configuration → Edge vs. non-edge routing.

fetchSearchInit()

Session bootstrap — resolves the visitor, returns their history (browsed / cart / purchased product ids), a lean feature-flag config (no filter definitions, no filter tree), the storefront token and a fresh visit_id. GloodProvider runs this automatically on mount; call it directly only for SSR or non-React use.

async function fetchSearchInit(
  options: FetchSearchOptions,
  params?: SearchInitParams
): Promise<SearchInitResponse>

fetchSearchConfig()

async function fetchSearchConfig(
  options: FetchSearchOptions,
  params?: SearchConfigParams
): Promise<SearchConfigResponse>

fetchInstantSearch()

query is required (may be ""); throws locally if query is undefined/null.

async function fetchInstantSearch(
  options: FetchSearchOptions,
  params: InstantSearchParams
): Promise<InstantSearchResponse>

fetchFilters()

async function fetchFilters(
  options: FetchSearchOptions,
  params?: FiltersParams
): Promise<FiltersResponse>

fetchFilterAggregations()

async function fetchFilterAggregations(
  options: FetchSearchOptions,
  params?: FilterAggregationsParams
): Promise<FilterAggregationsResponse>

fetchSearchResults()

async function fetchSearchResults(
  options: FetchSearchOptions,
  params?: SearchParams
): Promise<SearchResponse>

export async function loader({ request, context }) {
  const q = new URL(request.url).searchParams.get('q') ?? '';
  const results = await fetchSearchResults(
    { apiKey: context.env.GLOOD_API_KEY, myShopifyDomain: 'your-store.myshopify.com' },
    { query: q, pagination: { page: 1, limit: 24 } },
  ).catch(() => null);
  return { results };
}

fetchImageSearch()

Exactly one of image / imageUrl is required (throws locally otherwise).

async function fetchImageSearch(
  options: FetchSearchOptions,
  params: ImageSearchParams
): Promise<ImageSearchResponse>

sendSearchEvent()

The v1 analogue of sendHeadlessEvent. In the browser, channel ('hydrogen'), session_id, client_id and visitor_id are filled from cookies when omitted. Extra snake_case fields (cart, customer, customer_privacy, …) pass through. For SSR / non-React use; inside React prefer the SearchApp track helpers wired up by GloodProvider.

async function sendSearchEvent(
  options: FetchSearchOptions,
  params: HeadlessEventParams
): Promise<HeadlessEventResponse>

await sendSearchEvent(
  { apiKey, myShopifyDomain },
  {
    event: {
      id: crypto.randomUUID(),
      name: 'glood:search_result_clicked',
      type: 'custom',
      timestamp: new Date().toISOString(),
      // Search events are fully snake_case; context is required (navigator.user_agent).
      context: { navigator: { user_agent: navigator.userAgent } },
      custom_data: { track: { request_id, search_term: 'shoe', products: [{ product_id: '123' }] } },
    },
    channel: 'HYDROGEN',
  },
);

event.timestamp must be an ISO 8601 string within ±2 days of now (server rule). The events API requires at least one of visitor_id / client_id (defaulted from cookies in the browser).

Errors — GloodApiError

Thrown by every standalone function on a non-2xx response (re-exported from the search module):

import { GloodApiError } from '@glood/hydrogen';

try {
  await fetchSearchResults(options, params);
} catch (error) {
  if (error instanceof GloodApiError && error.status === 401) {
    // Invalid or mismatched API key
  }
}

SearchApp

The app instance registered via client.use(search()). Retrieve it from the client for advanced / SSR usage:

import { SearchApp } from '@glood/hydrogen';

const app = client.getApp('search') as SearchApp;

Methods

Method	Signature	Description
`init`	`(params?: SearchInitParams) => Promise<SearchInitResponse>`	Session bootstrap (visitor + history + lean config + token). `GloodProvider` runs it once on mount
`config`	`(params?: SearchConfigParams) => Promise<SearchConfigResponse>`	Fetch the search config
`instantSearch`	`(params: InstantSearchParams) => Promise<InstantSearchResponse>`	Instant search
`filters`	`(params?: FiltersParams) => Promise<FiltersResponse>`	Facet definitions
`search`	`(params?: SearchParams) => Promise<SearchResponse>`	Full product search
`imageSearch`	`(params: ImageSearchParams) => Promise<ImageSearchResponse>`	Visual search

const res = await app.search({ query: 'shoe', pagination: { limit: 24 } });

Event helpers

Each emits a glood:search:* custom event via the pixel pipeline and returns void:

trackSearch(track: SearchTrack): void        // glood:instant_search_triggered
trackResultView(track: SearchTrack): void     // glood:search_result_rendered
trackResultClick(track: SearchTrack): void    // glood:search_result_clicked
trackAddToCart(track: SearchTrack): void       // glood:search:add_to_cart
trackFilter(track: SearchTrack): void          // glood:search_filter_updated

app.trackResultClick({
  request_id: res.request_id,
  search_term: 'shoe',
  search_type: 'text',
  products: [{ product_id: '9311227838783', variant_id: '48792371233087', quantity: 1 }],
  filters: [{ key: 'color', value: ['red'] }],
  source: 'search_page',
});

Track events respect the app’s pixel config: if pixel.enabled is false, they are not sent.

search() module

Factory that creates and configures the search app. Pass { events } to narrow the standard Shopify events forwarded to the search backend (default: all events).

function search(options?: { events?: EventType[] }): GloodAppModule

import { createGlood, search } from '@glood/hydrogen';

const glood = createGlood({ apiKey, myShopifyDomain })
  .use(search({ events: ['search_submitted', 'product_added_to_cart'] }));

SearchTrack object

Attribution payload for glood:search:* events (snake_case wire shape):

interface SearchTrack {
  request_id?: string;      // request_id from the search response
  search_term?: string;
  search_type?: string;     // 'text' | 'image'
  products?: Array<{ product_id: string | number; variant_id?: string | number; quantity?: number }>;
  filters?: Array<{ key: string; value: string | string[] }>;
  source?: string;
  page_type?: string;
}

Response shapes

The key response types (SearchResponse, InstantSearchResponse, SearchConfigResponse, FiltersResponse, FilterAggregationsResponse, ImageSearchResponse) and the shared SearchProduct object are documented in full in TypeScript Types → Search API Types.

Example — SearchResponse

{
  "status": "ok",
  "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "products": [
    {
      "product_id": 9311227838783,
      "title": "Running Shoe",
      "handle": "running-shoe",
      "price": 49.99,
      "compare_at_price": 69.99,
      "display_price": 49.99,
      "display_currency": "USD",
      "available_for_sale": true,
      "is_in_stock": true,
      "image": { "url": "https://cdn.shopify.com/...", "alt_text": "Running Shoe" },
      "options": [{ "id": 111, "name": "Size", "position": 1, "values": ["S", "M", "L"] }],
      "variants": [
        {
          "variant_id": 456,
          "title": "M",
          "price": 49.99,
          "selected_options": [{ "name": "Size", "value": "M" }]
        }
      ],
      "metafields": [{ "namespace": "custom", "key": "material", "value": "leather" }]
    }
  ],
  "pagination": {
    "total": 240, "page": 1, "limit": 24, "total_pages": 10,
    "has_next_page": true, "has_prev_page": false, "next_page": 2, "prev_page": null
  },
  "facets": [
    { "key": "color", "type": "terms", "aggregation": { "buckets": [{ "value": "red", "count": 42, "selected": true }] } }
  ],
  "metadata": { "query_time": 40, "total_time": 55, "region": "toronto", "search_type": "hybrid" }
}

For Developers

Search API

Search API

Hooks

useSearch()

useInstantSearch()

useSearchConfig()

useSearchInit() / useSearchInitReady()

Standalone functions

Endpoints

fetchSearchInit()

fetchSearchConfig()

fetchInstantSearch()

fetchFilters()

fetchFilterAggregations()

fetchSearchResults()

fetchImageSearch()

sendSearchEvent()

Errors — GloodApiError

SearchApp

Methods

Event helpers

search() module

SearchTrack object

Response shapes

Example — SearchResponse

See Also

​Search API

​Hooks

​useSearch()

​useInstantSearch()

​useSearchConfig()

​useSearchInit() / useSearchInitReady()

​Standalone functions

​Endpoints

​fetchSearchInit()

​fetchSearchConfig()

​fetchInstantSearch()

​fetchFilters()

​fetchFilterAggregations()

​fetchSearchResults()

​fetchImageSearch()

​sendSearchEvent()

​Errors — GloodApiError

​SearchApp

​Methods

​Event helpers

​search() module

​SearchTrack object

​Response shapes

​Example — SearchResponse

​See Also

Search API

Hooks

useSearch()

useInstantSearch()

useSearchConfig()

useSearchInit() / useSearchInitReady()

Standalone functions

Endpoints

fetchSearchInit()

fetchSearchConfig()

fetchInstantSearch()

fetchFilters()

fetchFilterAggregations()

fetchSearchResults()

fetchImageSearch()

sendSearchEvent()

Errors — GloodApiError

SearchApp

Methods

Event helpers

search() module

SearchTrack object

Response shapes

Example — SearchResponse

See Also