Parameters and request types

Send the fields as a JSON body with POST /v1/search, or as query parameters with GET /v1/search. Only query is required.

curl -s https://api.packetstream.io/v1/search \
  -H "Authorization: Bearer $PACKETSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "espresso machines", "type": "shopping", "country": "gb", "page": 2}'

The same search as a GET:

curl -s -G https://api.packetstream.io/v1/search \
  -H "Authorization: Bearer $PACKETSTREAM_API_KEY" \
  --data-urlencode "query=espresso machines" \
  --data-urlencode "type=shopping" \
  --data-urlencode "country=gb" \
  --data-urlencode "page=2"

Request fields

Validation rules:

• Unknown, repeated, and mistyped fields return 400 invalid_request. The message names the field, for example unknown request field "engine".
• A JSON null counts as an omitted field.
• In a GET, booleans are true or false, integers are plain decimal digits, and each parameter may appear once.
• A POST body may be at most 4,096 bytes, and so may a GET query string.

Request types

Each type accepts only the options listed. Any other option returns 400 unsupported_option before any charge, for example device is not supported for type news. Sending an option’s default value, such as "device": "desktop" or "page": 1, is always accepted. format works with every type, and every type costs the same.

The API never drops an option silently. If no search source can serve a supported combination at the moment, the request fails with 400 unsupported_option and is not billed.

Responses lists the fields each type returns.

Batch searches

POST /v1/search/batch runs 1 to 10 searches in one request:

curl -s https://api.packetstream.io/v1/search/batch \
  -H "Authorization: Bearer $PACKETSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"searches": [
        {"query": "coffee grinders"},
        {"query": "coffee grinders", "type": "shopping"},
        {"query": "coffee grinders", "type": "news", "device": "mobile"}
      ]}'

The body is one JSON object whose only field is searches, an array of 1 to 10 items. Each item takes the request fields, and its format can only be json. The body may be at most 16 KiB.

The response lists one entry per item, in request order. Each entry has the item’s index, the HTTP status the item would have received on its own, and either the full search response or an error. In this shape, … stands for the left-out search fields:

{
  "request_id": "0b8f6c3e-5a2d-4c71-9e40-7d1f2a6b9c58",
  "results": [
    { "index": 0, "status": 200, "request_id": "0b8f6c3e-…", "search": {…}, "results": […], "charged_units": 1, … },
    { "index": 1, "status": 200, "request_id": "0b8f6c3e-…", "search": {…}, "results": […], "charged_units": 1, … },
    { "index": 2, "status": 400, "error": { "code": "unsupported_option", "message": "device is not supported for type news" } }
  ],
  "charged_units": 2
}

• A valid batch returns HTTP 200 even when some items fail, so check each entry’s status.
• Each item is a separate search. It is validated, rate-limited, checked against your balance, billed, and logged like a single search. The top-level charged_units counts the successful items.
• Entries share the batch request_id. The request ID and index together identify an item.
• Items are admitted in order, so when the rate limit or your balance runs out, later items fail first. A 10-item batch uses the key’s whole burst of 10.
• Items run at the same time and share one 25-second deadline.
• A malformed body, such as one without searches or with more than 10 items, returns 400 invalid_request for the whole request.