Resolve product query to nearby store availability

curl --request POST \
  --url https://www.closient.com/agent/api/v1/resolve \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "<string>",
  "location": {
    "latitude": 0,
    "longitude": 0
  },
  "constraints": {
    "allergen_free": [
      "Peanuts"
    ],
    "category_path": "Food, Beverages & Tobacco > Beverages",
    "certifications": [
      "USDA Organic"
    ],
    "claims": [
      "Vegan"
    ],
    "exclude_major_allergens": true,
    "nutrients_max": {
      "SODIUM": 140
    },
    "nutrients_min": {
      "PROTEIN": 20
    },
    "price_max": 9.99
  },
  "radius_km": 10,
  "limit": 5
}
'

import requests

url = "https://www.closient.com/agent/api/v1/resolve"

payload = {
    "query": "<string>",
    "location": {
        "latitude": 0,
        "longitude": 0
    },
    "constraints": {
        "allergen_free": ["Peanuts"],
        "category_path": "Food, Beverages & Tobacco > Beverages",
        "certifications": ["USDA Organic"],
        "claims": ["Vegan"],
        "exclude_major_allergens": True,
        "nutrients_max": { "SODIUM": 140 },
        "nutrients_min": { "PROTEIN": 20 },
        "price_max": 9.99
    },
    "radius_km": 10,
    "limit": 5
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: '<string>',
    location: {latitude: 0, longitude: 0},
    constraints: {
      allergen_free: ['Peanuts'],
      category_path: 'Food, Beverages & Tobacco > Beverages',
      certifications: ['USDA Organic'],
      claims: ['Vegan'],
      exclude_major_allergens: true,
      nutrients_max: {SODIUM: 140},
      nutrients_min: {PROTEIN: 20},
      price_max: 9.99
    },
    radius_km: 10,
    limit: 5
  })
};

fetch('https://www.closient.com/agent/api/v1/resolve', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.closient.com/agent/api/v1/resolve",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => '<string>',
    'location' => [
        'latitude' => 0,
        'longitude' => 0
    ],
    'constraints' => [
        'allergen_free' => [
                'Peanuts'
        ],
        'category_path' => 'Food, Beverages & Tobacco > Beverages',
        'certifications' => [
                'USDA Organic'
        ],
        'claims' => [
                'Vegan'
        ],
        'exclude_major_allergens' => true,
        'nutrients_max' => [
                'SODIUM' => 140
        ],
        'nutrients_min' => [
                'PROTEIN' => 20
        ],
        'price_max' => 9.99
    ],
    'radius_km' => 10,
    'limit' => 5
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/agent/api/v1/resolve"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"location\": {\n    \"latitude\": 0,\n    \"longitude\": 0\n  },\n  \"constraints\": {\n    \"allergen_free\": [\n      \"Peanuts\"\n    ],\n    \"category_path\": \"Food, Beverages & Tobacco > Beverages\",\n    \"certifications\": [\n      \"USDA Organic\"\n    ],\n    \"claims\": [\n      \"Vegan\"\n    ],\n    \"exclude_major_allergens\": true,\n    \"nutrients_max\": {\n      \"SODIUM\": 140\n    },\n    \"nutrients_min\": {\n      \"PROTEIN\": 20\n    },\n    \"price_max\": 9.99\n  },\n  \"radius_km\": 10,\n  \"limit\": 5\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.closient.com/agent/api/v1/resolve")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"location\": {\n    \"latitude\": 0,\n    \"longitude\": 0\n  },\n  \"constraints\": {\n    \"allergen_free\": [\n      \"Peanuts\"\n    ],\n    \"category_path\": \"Food, Beverages & Tobacco > Beverages\",\n    \"certifications\": [\n      \"USDA Organic\"\n    ],\n    \"claims\": [\n      \"Vegan\"\n    ],\n    \"exclude_major_allergens\": true,\n    \"nutrients_max\": {\n      \"SODIUM\": 140\n    },\n    \"nutrients_min\": {\n      \"PROTEIN\": 20\n    },\n    \"price_max\": 9.99\n  },\n  \"radius_km\": 10,\n  \"limit\": 5\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/agent/api/v1/resolve")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"<string>\",\n  \"location\": {\n    \"latitude\": 0,\n    \"longitude\": 0\n  },\n  \"constraints\": {\n    \"allergen_free\": [\n      \"Peanuts\"\n    ],\n    \"category_path\": \"Food, Beverages & Tobacco > Beverages\",\n    \"certifications\": [\n      \"USDA Organic\"\n    ],\n    \"claims\": [\n      \"Vegan\"\n    ],\n    \"exclude_major_allergens\": true,\n    \"nutrients_max\": {\n      \"SODIUM\": 140\n    },\n    \"nutrients_min\": {\n      \"PROTEIN\": 20\n    },\n    \"price_max\": 9.99\n  },\n  \"radius_km\": 10,\n  \"limit\": 5\n}"

response = http.request(request)
puts response.read_body

{
  "results": []
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "retryable": true,
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "retryable": true,
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "retryable": true,
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "retryable": true,
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "retryable": true,
  "timestamp": "2023-11-07T05:31:56Z"
}

Resolve

Resolve product query to nearby store availability

Accepts a natural-language product query plus a geographic anchor and optional filtering constraints (certifications, allergens, substances, price, nutrients) and returns ranked product matches with real-time nearby store availability.

Ranking is a blend of semantic similarity to query, proximity to location.latitude/location.longitude (within radius_km), and constraint compliance. Each result carries a list of StoreAvailabilityOut rows sorted closest-first.

Constraints in the payload are merged with the authenticated user’s saved preferences (explicit payload wins on conflict); a missing constraints key means use the user’s preferences as-is.

Empty results return 200 with results: [] — the endpoint does not 404 when nothing matches.

POST

agent

api

resolve

Resolve product query to nearby store availability

curl --request POST \
  --url https://www.closient.com/agent/api/v1/resolve \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "query": "<string>",
  "location": {
    "latitude": 0,
    "longitude": 0
  },
  "constraints": {
    "allergen_free": [
      "Peanuts"
    ],
    "category_path": "Food, Beverages & Tobacco > Beverages",
    "certifications": [
      "USDA Organic"
    ],
    "claims": [
      "Vegan"
    ],
    "exclude_major_allergens": true,
    "nutrients_max": {
      "SODIUM": 140
    },
    "nutrients_min": {
      "PROTEIN": 20
    },
    "price_max": 9.99
  },
  "radius_km": 10,
  "limit": 5
}
'

import requests

url = "https://www.closient.com/agent/api/v1/resolve"

payload = {
    "query": "<string>",
    "location": {
        "latitude": 0,
        "longitude": 0
    },
    "constraints": {
        "allergen_free": ["Peanuts"],
        "category_path": "Food, Beverages & Tobacco > Beverages",
        "certifications": ["USDA Organic"],
        "claims": ["Vegan"],
        "exclude_major_allergens": True,
        "nutrients_max": { "SODIUM": 140 },
        "nutrients_min": { "PROTEIN": 20 },
        "price_max": 9.99
    },
    "radius_km": 10,
    "limit": 5
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    query: '<string>',
    location: {latitude: 0, longitude: 0},
    constraints: {
      allergen_free: ['Peanuts'],
      category_path: 'Food, Beverages & Tobacco > Beverages',
      certifications: ['USDA Organic'],
      claims: ['Vegan'],
      exclude_major_allergens: true,
      nutrients_max: {SODIUM: 140},
      nutrients_min: {PROTEIN: 20},
      price_max: 9.99
    },
    radius_km: 10,
    limit: 5
  })
};

fetch('https://www.closient.com/agent/api/v1/resolve', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://www.closient.com/agent/api/v1/resolve",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'query' => '<string>',
    'location' => [
        'latitude' => 0,
        'longitude' => 0
    ],
    'constraints' => [
        'allergen_free' => [
                'Peanuts'
        ],
        'category_path' => 'Food, Beverages & Tobacco > Beverages',
        'certifications' => [
                'USDA Organic'
        ],
        'claims' => [
                'Vegan'
        ],
        'exclude_major_allergens' => true,
        'nutrients_max' => [
                'SODIUM' => 140
        ],
        'nutrients_min' => [
                'PROTEIN' => 20
        ],
        'price_max' => 9.99
    ],
    'radius_km' => 10,
    'limit' => 5
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.closient.com/agent/api/v1/resolve"

	payload := strings.NewReader("{\n  \"query\": \"<string>\",\n  \"location\": {\n    \"latitude\": 0,\n    \"longitude\": 0\n  },\n  \"constraints\": {\n    \"allergen_free\": [\n      \"Peanuts\"\n    ],\n    \"category_path\": \"Food, Beverages & Tobacco > Beverages\",\n    \"certifications\": [\n      \"USDA Organic\"\n    ],\n    \"claims\": [\n      \"Vegan\"\n    ],\n    \"exclude_major_allergens\": true,\n    \"nutrients_max\": {\n      \"SODIUM\": 140\n    },\n    \"nutrients_min\": {\n      \"PROTEIN\": 20\n    },\n    \"price_max\": 9.99\n  },\n  \"radius_km\": 10,\n  \"limit\": 5\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://www.closient.com/agent/api/v1/resolve")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"query\": \"<string>\",\n  \"location\": {\n    \"latitude\": 0,\n    \"longitude\": 0\n  },\n  \"constraints\": {\n    \"allergen_free\": [\n      \"Peanuts\"\n    ],\n    \"category_path\": \"Food, Beverages & Tobacco > Beverages\",\n    \"certifications\": [\n      \"USDA Organic\"\n    ],\n    \"claims\": [\n      \"Vegan\"\n    ],\n    \"exclude_major_allergens\": true,\n    \"nutrients_max\": {\n      \"SODIUM\": 140\n    },\n    \"nutrients_min\": {\n      \"PROTEIN\": 20\n    },\n    \"price_max\": 9.99\n  },\n  \"radius_km\": 10,\n  \"limit\": 5\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://www.closient.com/agent/api/v1/resolve")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"query\": \"<string>\",\n  \"location\": {\n    \"latitude\": 0,\n    \"longitude\": 0\n  },\n  \"constraints\": {\n    \"allergen_free\": [\n      \"Peanuts\"\n    ],\n    \"category_path\": \"Food, Beverages & Tobacco > Beverages\",\n    \"certifications\": [\n      \"USDA Organic\"\n    ],\n    \"claims\": [\n      \"Vegan\"\n    ],\n    \"exclude_major_allergens\": true,\n    \"nutrients_max\": {\n      \"SODIUM\": 140\n    },\n    \"nutrients_min\": {\n      \"PROTEIN\": 20\n    },\n    \"price_max\": 9.99\n  },\n  \"radius_km\": 10,\n  \"limit\": 5\n}"

response = http.request(request)
puts response.read_body

{
  "results": []
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "retryable": true,
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "retryable": true,
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "retryable": true,
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "retryable": true,
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "type": "<string>",
  "title": "<string>",
  "status": 123,
  "detail": "<string>",
  "error_code": "<string>",
  "retryable": true,
  "timestamp": "2023-11-07T05:31:56Z"
}

Authorizations

X-API-Key

string

header

required

Body

application/json

Input for the product resolution endpoint.

Encapsulates a free-form shopper question, a geographic anchor, and optional constraints. The agent API combines these with the authenticated user's saved preferences (explicit payload wins on conflict) to produce ranked product matches with nearby store availability.

query

string

required

Natural-language product query as the shopper would phrase it (e.g. 'organic almond milk', 'gluten-free pasta sauce'). The resolver runs hybrid semantic + lexical search; brand and category hints in the query are used for ranking.

Required string length: 1 - 500

location

LocationIn · object

required

Shopper's geographic anchor for proximity ranking. Stores within radius_km of this point are considered for availability.

Show child attributes

Example:

{ "latitude": 40.7128, "longitude": -74.006 }

constraints

ConstraintsIn · object | null

Optional product-filter constraints. Merged with the authenticated user's saved preferences (explicit payload wins on conflict). Null means use the user's preferences as-is.

Show child attributes

Example:

{
  "allergen_free": ["Peanuts"],
  "category_path": "Food, Beverages & Tobacco > Beverages",
  "certifications": ["USDA Organic"],
  "claims": ["Vegan"],
  "exclude_major_allergens": true,
  "nutrients_max": { "SODIUM": 140 },
  "nutrients_min": { "PROTEIN": 20 },
  "price_max": 9.99
}

radius_km

number

default:10

Search radius in kilometers from location. Stores beyond this distance are excluded from availability. Capped at 100 km.

Required range: x <= 100

limit

integer

default:5

Maximum number of distinct product results to return. Each product may carry multiple StoreAvailabilityOut entries — this bound is on the product count, not the per-store availability list.

Required range: 1 <= x <= 25

Response

Response from the POST /resolve endpoint.

Top-level container holds the ranked product matches; the ranking is a blend of semantic similarity to query, proximity to location, and constraint compliance.

results

ResolveResultOut · object[]

Matched products with their nearby store availability, ranked best-match first. Empty list when nothing matches the query and constraints; the endpoint does not 404 on no-match.

Show child attributes

Overview

Account

Products

Brands

Locations

Retailers

Search

GS1 Digital Link

EPCIS 2.0

Integrations

Billing

Scanner

Compliance

Certifications

Sustainability

Notifications

Dashboard

Analytics

Agent

Substances

BYOS

Content

Signals

Resolve product query to nearby store availability

Authorizations

Body

Response