API Documentation

Learn how to use the Product Search API with location hints and image search

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

X-API-KEY: your-api-key-here

You can create and manage API keys from your dashboard.

Basic Usage

The Product Search API allows you to search for products. The endpoint accepts a search query and optional parameters to customize your results.

POST https://productapi.dev/api?search=your+search+query

Headers:
  X-API-KEY: your-api-key-here

Location Hint Parameter

The location-hint parameter allows you to bias search results toward products available in a specific country.

How it works:

Influences results to prefer products available in the specified location
Optimizes image search results for that geographic region
Uses ISO 3166-1 alpha-2 two-letter country codes (e.g., "us", "uk", "jp")

Usage Example:

POST https://productapi.dev/api?search=laptop&location-hint=us

Headers:
  X-API-KEY: your-api-key-here

Valid Country Codes:

The location-hint parameter accepts any valid two-letter ISO 3166-1 alpha-2 country code. Supported countries include:

usUnited States

ukUnited Kingdom

caCanada

auAustralia

deGermany

frFrance

The API accepts all standard ISO country codes. Invalid codes will return a 400 error.

Response Language Parameter

The response_language parameter allows you to specify the language in which product information (name, description, brand) should be returned. This ensures that all product details are provided in your preferred language. If not provided, the response will guess based on the search query.

How it works:

All product information (name, description, brand) will be provided in the specified language
Uses ISO 639-1 two-letter language codes (e.g., "fr", "es", "de", "ja")
Works independently of the search query language

Usage Example:

POST https://productapi.dev/api?search=laptop&response_language=fr

Headers:
  X-API-KEY: your-api-key-here

Valid Language Codes:

The response_language parameter accepts valid two-letter ISO 639-1 language codes. Supported languages include:

afAfrikaans

sqAlbanian

amAmharic

arArabic

hyArmenian

asAssamese

Invalid language codes will return a 400 error.

With Image Parameter

The with_image parameter controls whether product results include image URLs. When enabled, the API performs additional image searches for each product and includes the image URL in the response.

Important Notes:

Set with_image=true to include images
When with_image is false or omitted, products won't include image URLs
Image searches use the location-hint if provided
Each API call consumes 1 credit regardless of with_image setting

Usage Examples:

With Images Enabled:

POST https://productapi.dev/api?search=wireless+headphones&with_image=true

Headers:
  X-API-KEY: your-api-key-here

Response includes image URLs:

{
  "search": "wireless headphones",
  "products": [
    {
      "name": "Sony WH-1000XM5",
      "description": "Premium noise-cancelling wireless headphones",
      "brand": "Sony",
      "image": "https://example.com/sony-headphones.jpg"
    }
  ],
  "creditsUsed": 1,
  "creditsRemaining": 49
}

Without Images (default):

POST https://productapi.dev/api?search=wireless+headphones

Headers:
  X-API-KEY: your-api-key-here

Response without image URLs:

{
  "search": "wireless headphones",
  "products": [
    {
      "name": "Sony WH-1000XM5",
      "description": "Premium noise-cancelling wireless headphones",
      "brand": "Sony"
    }
  ],
  "creditsUsed": 1,
  "creditsRemaining": 49
}

Custom Data Schema Parameter

The custom_data_schema parameter allows you to define additional structured data fields that should be included in each product result. This is sent in the request body as a JSON schema, and the api will respond with a custom_data field for each product according to your schema.

How it works:

Send a POST request with a JSON body containing custom_data_schema
The schema must be a valid JSON Schema object (validated using AJV)
Each product in the response will include a custom_data field
Useful for extracting specific fields like price ranges, availability, ratings, specifications, etc.

Usage Example:

POST https://productapi.dev/api?search=wireless+headphones

Headers:
  X-API-KEY: your-api-key-here
  Content-Type: application/json

Body:
{
  "custom_data_schema": {
    "type": "object",
    "properties": {
      "price_range": { "type": "string" },
      "availability": { "type": "string" },
      "rating": { "type": "number" }
    },
    "required": ["price_range", "availability"]
  }
}

Example Response:

{
  "search": "wireless headphones",
  "products": [
    {
      "name": "Sony WH-1000XM5",
      "description": "Premium noise-cancelling wireless headphones",
      "brand": "Sony",
      "custom_data": {
        "price_range": "$300-$400",
        "availability": "In Stock",
        "rating": 4.8
      }
    }
  ],
  "creditsUsed": 1,
  "creditsRemaining": 49
}

Important Notes:

Must be sent as a POST request (GET requests don't support request bodies)
The schema must be a valid JSON Schema object - invalid schemas will return a 400 error
Supports nested objects, arrays, and all standard JSON Schema types

Complex Schema Example:

POST https://productapi.dev/api?search=laptop

Headers:
  X-API-KEY: your-api-key-here
  Content-Type: application/json

Body:
{
  "custom_data_schema": {
    "type": "object",
    "properties": {
      "price": {
        "type": "object",
        "properties": {
          "min": { "type": "number" },
          "max": { "type": "number" },
          "currency": { "type": "string" }
        },
        "required": ["min", "max", "currency"]
      },
      "specifications": {
        "type": "object",
        "properties": {
          "ram": { "type": "string" },
          "storage": { "type": "string" },
          "processor": { "type": "string" }
        }
      },
      "in_stock": { "type": "boolean" }
    },
    "required": ["price", "in_stock"]
  }
}

Combined Usage

You can combine all parameters to get location-specific products with images in your preferred language and custom data fields:

POST Request (without custom_data_schema):

POST https://productapi.dev/api?search=smartphone&location-hint=jp&with_image=true&response_language=fr

Headers:
  X-API-KEY: your-api-key-here

This will return products preferred for Japan with image URLs included, all in French.

POST Request (with custom_data_schema):

POST https://productapi.dev/api?search=smartphone&location-hint=jp&with_image=true&response_language=fr

Headers:
  X-API-KEY: your-api-key-here
  Content-Type: application/json

Body:
{
  "custom_data_schema": {
    "type": "object",
    "properties": {
      "price_range": { "type": "string" },
      "availability": { "type": "string" }
    },
    "required": ["price_range"]
  }
}

This will return products preferred for Japan with image URLs included, all in French, with custom data fields populated according to your schema.

Response Format

Success Response (200):

{
  "search": "wireless headphones",
  "products": [
    {
      "name": "Sony WH-1000XM5",
      "description": "Premium noise-cancelling wireless headphones",
      "brand": "Sony",
      "image": "https://example.com/sony-headphones.jpg"
    }
  ],
  "creditsUsed": 1,
  "creditsRemaining": 49
}

Error Responses:

400 Bad Request - Missing search parameter:

{
  "error": "Missing required query parameter: 'search'"
}

400 Bad Request - Invalid location-hint:

{
  "error": "Invalid location-hint parameter: 'invalid'. Must be a valid two-letter country code."
}

400 Bad Request - Invalid response_language:

{
  "error": "Invalid response_language parameter: 'invalid'. Must be a valid two-letter language code."
}

400 Bad Request - Invalid custom_data_schema:

{
  "error": "Invalid custom_data_schema: /properties: must be object"
}

400 Bad Request - Invalid JSON in request body:

{
  "error": "Invalid JSON in request body"
}

401 Unauthorized - Missing API key:

{
  "error": "Unauthorized. Please provide a valid API key."
}

401 Unauthorized - Invalid API key:

{
  "error": "Invalid API key."
}

402 Payment Required - Insufficient credits:

{
  "error": "Insufficient credits",
  "creditsRequired": 1,
  "creditsAvailable": 0
}

404 Not Found - No products found:

{
  "error": "No products found"
}

Credits & Pricing

• Each API call consumes 1 credit, regardless of parameters
• Credits are deducted after a successful API call
• Check your remaining credits in the response or your dashboard
• Purchase additional credits from your dashboard

Code Examples

JavaScript (Fetch API):

POST Request:

const response = await fetch(
  'https://productapi.dev/api?search=laptop&location-hint=us&with_image=true&response_language=en',
  {
    method: 'POST',
    headers: {
      'X-API-KEY': 'your-api-key-here'
    }
  }
);

const data = await response.json();
console.log(data);

POST Request with custom_data_schema:

const response = await fetch(
  'https://productapi.dev/api?search=laptop&location-hint=us&with_image=true&response_language=en',
  {
    method: 'POST',
    headers: {
      'X-API-KEY': 'your-api-key-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      custom_data_schema: {
        type: 'object',
        properties: {
          price_range: { type: 'string' },
          availability: { type: 'string' }
        },
        required: ['price_range']
      }
    })
  }
);

const data = await response.json();
console.log(data);

Python (requests):

POST Request:

import requests

url = 'https://productapi.dev/api'
params = {
    'search': 'laptop',
    'location-hint': 'us',
    'with_image': 'true',
    'response_language': 'en'
}
headers = {
    'X-API-KEY': 'your-api-key-here'
}

response = requests.post(url, params=params, headers=headers)
data = response.json()
print(data)

POST Request with custom_data_schema:

import requests

url = 'https://productapi.dev/api'
params = {
    'search': 'laptop',
    'location-hint': 'us',
    'with_image': 'true',
    'response_language': 'en'
}
headers = {
    'X-API-KEY': 'your-api-key-here',
    'Content-Type': 'application/json'
}
body = {
    'custom_data_schema': {
        'type': 'object',
        'properties': {
            'price_range': {'type': 'string'},
            'availability': {'type': 'string'}
        },
        'required': ['price_range']
    }
}

response = requests.post(url, params=params, headers=headers, json=body)
data = response.json()
print(data)

cURL:

POST Request:

curl -X POST \
  "https://productapi.dev/api?search=laptop&location-hint=us&with_image=true&response_language=en" \
  -H "X-API-KEY: your-api-key-here"

POST Request with custom_data_schema:

curl -X POST \
  "https://productapi.dev/api?search=laptop&location-hint=us&with_image=true&response_language=en" \
  -H "X-API-KEY: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_data_schema": {
      "type": "object",
      "properties": {
        "price_range": {"type": "string"},
        "availability": {"type": "string"}
      },
      "required": ["price_range"]
    }
  }'

Need help? Visit your dashboard to manage API keys and credits.