API-Referenz

GET /api/v1/datasets

Your datasets

The datasets your plan lets you read, with how many items and websites each has and when its sources were last read. Their id is the dataset filter of the other requests.

Antworten

• 200 Your datasets. application/json Dataset[]
• 401 No API key, or one that is invalid or revoked. application/json Error
• 402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
• 429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Beispiel

[
  {
    "description": "Laptops and notebooks from shops in Germany, Austria and Switzerland.",
    "healthyModels": 14,
    "id": 12,
    "items": 18342,
    "models": 14,
    "name": "Laptops DACH",
    "newestScrapeAt": "2026-10-07T09:12:00Z",
    "oldestScrapeAt": "2026-10-07T05:40:00Z",
    "sites": 9
  }
]

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/datasets"

GET /api/v1/facets

Websites, categories and currencies to filter by

The values the items can be filtered by, each with the number of items listed now.

Parameter

Antworten

• 200 The facets. application/json Facets
• 401 No API key, or one that is invalid or revoked. application/json Error
• 402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
• 404 No such dataset of yours. application/json Error
• 429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Beispiel

{
  "categories": [
    {
      "id": 8,
      "items": 1804,
      "name": "Laptops",
      "parentId": 2,
      "path": "Computers > Laptops",
      "slug": "computers-laptops"
    }
  ],
  "currencies": [
    {
      "code": "EUR",
      "items": 17920
    }
  ],
  "sites": [
    {
      "host": "www.notebookshop.example",
      "id": 4,
      "items": 2310,
      "name": "Notebookshop"
    }
  ]
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/facets"

GET /api/v1/items

Find items

Items of your datasets, filtered and sorted, a page at a time (up to 500). To keep a copy in sync, use the change feed (/changes) or changedSince.

Parameter

Antworten

• 200 A page of items. application/json PageDtoItem
• 400 A parameter is not valid; message says which. application/json Error
• 401 No API key, or one that is invalid or revoked. application/json Error
• 402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
• 429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Beispiel

{
  "content": [
    {
      "attributes": {
        "availability": "in stock",
        "shipping": 0
      },
      "brand": "Lenovo",
      "category": {
        "name": null,
        "path": null,
        "slug": null,
        "source": null
      },
      "currency": "EUR",
      "datasets": [
        "Laptops DACH"
      ],
      "firstSeenAt": "2026-09-01T10:00:00Z",
      "gtin": "0196802123456",
      "id": 77,
      "image": "https://www.notebookshop.example/img/thinkpad-x1.jpg",
      "lastChangedAt": "2026-10-06T21:03:00Z",
      "lastSeenAt": "2026-10-07T09:12:00Z",
      "mpn": "21KC004MGE",
      "previousPrice": 1499,
      "price": 1399,
      "priceChangedAt": "2026-10-06T21:03:00Z",
      "removedAt": "2026-10-07T03:30:00Z",
      "site": {
        "attribution": null,
        "host": null,
        "id": null,
        "name": null
      },
      "source": {
        "modelId": null,
        "name": null
      },
      "title": "Lenovo ThinkPad X1 Carbon Gen 12",
      "url": "https://www.notebookshop.example/p/thinkpad-x1"
    }
  ],
  "page": 0,
  "size": 50,
  "totalElements": 1804,
  "totalPages": 37
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/items"

GET /api/v1/items/{id}

One item

The item as it is now (as /items shows it), also once it is no longer listed.

Parameter

Antworten

• 200 The item. application/json Item
• 401 No API key, or one that is invalid or revoked. application/json Error
• 402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
• 404 Not found among the items you can see. application/json Error
• 429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Beispiel

{
  "attributes": {
    "availability": "in stock",
    "shipping": 0
  },
  "brand": "Lenovo",
  "category": {
    "name": "Laptops",
    "path": "Computers > Laptops",
    "slug": "computers-laptops",
    "source": "AI"
  },
  "currency": "EUR",
  "datasets": [
    "Laptops DACH"
  ],
  "firstSeenAt": "2026-09-01T10:00:00Z",
  "gtin": "0196802123456",
  "id": 77,
  "image": "https://www.notebookshop.example/img/thinkpad-x1.jpg",
  "lastChangedAt": "2026-10-06T21:03:00Z",
  "lastSeenAt": "2026-10-07T09:12:00Z",
  "mpn": "21KC004MGE",
  "previousPrice": 1499,
  "price": 1399,
  "priceChangedAt": "2026-10-06T21:03:00Z",
  "removedAt": "2026-10-07T03:30:00Z",
  "site": {
    "attribution": "Source: European Commission, Weekly Oil Bulletin, CC BY 4.0",
    "host": "www.notebookshop.example",
    "id": 4,
    "name": "Notebookshop"
  },
  "source": {
    "modelId": 31,
    "name": "Notebookshop – Laptops"
  },
  "title": "Lenovo ThinkPad X1 Carbon Gen 12",
  "url": "https://www.notebookshop.example/p/thinkpad-x1"
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/items/77"

GET /api/v1/items/{id}/history

An item's history

Every change of the item within your plan's history, oldest first: its prices over time.

Parameter

Antworten

• 200 The item's history. application/json HistoryEntry[]
• 401 No API key, or one that is invalid or revoked. application/json Error
• 402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
• 404 Not found among the items you can see. application/json Error
• 429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Beispiel

[
  {
    "changes": {
      "availability": [
        "2-3 days",
        "in stock"
      ]
    },
    "id": 812,
    "kind": "NEW",
    "observedAt": "2026-10-06T21:03:00Z",
    "previousPrice": 1499,
    "price": 1399
  }
]

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/items/77/history"

GET /api/v1/changes

The change feed

Everything that happened after after, oldest first. Start with after=0, then pass each answer's nextCursor as after; repeat while hasMore is true. Store the last cursor and go on from it next time: you get each change exactly once. Changes show here about 30 seconds after they happen. Paid plans (on Free it answers 402).

Parameter

Antworten

• 200 The next changes. application/json ChangePage
• 401 No API key, or one that is invalid or revoked. application/json Error
• 402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
• 429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Beispiel

{
  "changes": [
    {
      "changes": {
        "price": [
          1499,
          1399
        ]
      },
      "id": 812,
      "item": {
        "currency": null,
        "id": null,
        "site": null,
        "title": null,
        "url": null
      },
      "kind": "NEW",
      "observedAt": "2026-10-06T21:03:00Z",
      "previousPrice": 1499,
      "price": 1399
    }
  ],
  "hasMore": true,
  "nextCursor": 1811
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/changes"

GET /api/v1/changes/recent

Recent changes, newest first

For people: the latest changes, newest first, optionally only of one kind. Page back with before. To sync a copy, use /changes. A change shows here when it shows in /changes (within about 30 seconds), so the id of the newest one is a safe place to start /changes?after= from.

Parameter

Antworten

• 200 The changes. application/json ChangePage
• 400 A parameter is not valid; message says which. application/json Error
• 401 No API key, or one that is invalid or revoked. application/json Error
• 402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
• 429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Beispiel

{
  "changes": [
    {
      "changes": {
        "price": [
          1499,
          1399
        ]
      },
      "id": 812,
      "item": {
        "currency": null,
        "id": null,
        "site": null,
        "title": null,
        "url": null
      },
      "kind": "NEW",
      "observedAt": "2026-10-06T21:03:00Z",
      "previousPrice": 1499,
      "price": 1399
    }
  ],
  "hasMore": true,
  "nextCursor": 1811
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/changes/recent"

GET /api/v1/products

Find products across shops

Products with offers in your datasets: the same product in several shops, matched by GTIN, else by brand and part number, with its price range and how many shops sell it.

Parameter

Antworten

• 200 A page of products. application/json PageDtoProduct
• 400 A parameter is not valid; message says which. application/json Error
• 401 No API key, or one that is invalid or revoked. application/json Error
• 402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
• 429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Beispiel

{
  "content": [
    {
      "brand": "Lenovo",
      "category": {
        "name": null,
        "path": null,
        "slug": null,
        "source": null
      },
      "gtin": "0196802123456",
      "id": "0196802123456",
      "mpn": "21KC004MGE",
      "offers": 6,
      "prices": [
        null
      ],
      "shops": 5,
      "title": "Lenovo ThinkPad X1 Carbon Gen 12"
    }
  ],
  "page": 0,
  "size": 50,
  "totalElements": 1804,
  "totalPages": 37
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/products"

GET /api/v1/products/{id}

One product with its offers

A product by its id (a GTIN, or a brand-MPN key) with all its offers you can see, cheapest first.

Parameter

Antworten

• 200 The product and its offers. application/json ProductDetail
• 401 No API key, or one that is invalid or revoked. application/json Error
• 402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
• 404 No offers of this product among the items you can see. application/json Error
• 429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Beispiel

{
  "offers": [
    {
      "attributes": {
        "availability": "in stock",
        "shipping": 0
      },
      "brand": "Lenovo",
      "category": {
        "name": null,
        "path": null,
        "slug": null,
        "source": null
      },
      "currency": "EUR",
      "datasets": [
        "Laptops DACH"
      ],
      "firstSeenAt": "2026-09-01T10:00:00Z",
      "gtin": "0196802123456",
      "id": 77,
      "image": "https://www.notebookshop.example/img/thinkpad-x1.jpg",
      "lastChangedAt": "2026-10-06T21:03:00Z",
      "lastSeenAt": "2026-10-07T09:12:00Z",
      "mpn": "21KC004MGE",
      "previousPrice": 1499,
      "price": 1399,
      "priceChangedAt": "2026-10-06T21:03:00Z",
      "removedAt": "2026-10-07T03:30:00Z",
      "site": {
        "attribution": null,
        "host": null,
        "id": null,
        "name": null
      },
      "source": {
        "modelId": null,
        "name": null
      },
      "title": "Lenovo ThinkPad X1 Carbon Gen 12",
      "url": "https://www.notebookshop.example/p/thinkpad-x1"
    }
  ],
  "product": {
    "brand": "Lenovo",
    "category": {
      "name": "Laptops",
      "path": "Computers > Laptops",
      "slug": "computers-laptops",
      "source": "AI"
    },
    "gtin": "0196802123456",
    "id": "0196802123456",
    "mpn": "21KC004MGE",
    "offers": 6,
    "prices": [
      {
        "currency": null,
        "max": null,
        "min": null,
        "offers": null
      }
    ],
    "shops": 5,
    "title": "Lenovo ThinkPad X1 Carbon Gen 12"
  }
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/products/0196802123456"

GET /api/v1/export

Export items

All matching items, streamed as CSV (UTF-8, a header row) or NDJSON (one JSON object per line), with the filters of /items. Rows count against your plan's export rows per month. On paid plans, rows beyond them are billed as overage per started 10,000 and the export is complete (X-Export-Overage); on Free, in the trial, or with overage switched off, an export that would go beyond them ends at the limit and says so in X-Export-Truncated.

Parameter

Antworten

• 200 The rows, streamed. application/x-ndjson string text/csv string
  • X-Export-Matching: With X-Export-Truncated: how many rows matched.
  • X-Export-Overage: true if rows beyond the month's quota are in it, billed as overage.
  • X-Export-Rows: Rows in this export.
  • X-Export-Rows-Remaining: Export rows left this month after it.
  • X-Export-Truncated: true if the export ended at the monthly limit.
• 400 A parameter is not valid; message says which. application/json Error
• 401 No API key, or one that is invalid or revoked. application/json Error
• 402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
• 429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/export"

GET /api/v1/plan

Your plan and this month's use

The plan in effect, its limits (null is unlimited), the calls and export rows used this month and when they start over. Every answer also carries RateLimit-* and X-Quota-* headers.

Antworten

• 200 Your plan. application/json PlanInfo
• 401 No API key, or one that is invalid or revoked. application/json Error
• 402 Not in your plan (a dataset beyond it, the change feed on Free), or a payment overdue for 30 days (limit: paymentOverdue). application/json LimitError
• 429 Too many requests per second, or the month's calls are used up (limit says which). Retry-After says when to try again. application/json LimitError

Beispiel

{
  "limits": {
    "datasets": 10,
    "apiCallsPerMonth": 250000,
    "ratePerSecond": 20,
    "delayHours": 0,
    "historyDays": 365,
    "exportRowsPerMonth": 1000000,
    "changeFeed": true,
    "webhooks": true
  },
  "lockedDatasets": 0,
  "name": "Pro",
  "plan": "pro",
  "status": "ACTIVE",
  "trialEndsAt": "2026-10-21T09:00:00Z",
  "upgradeUrl": "https://pricana.io/pricing",
  "usage": {
    "apiCalls": 48211,
    "exportRows": 12000,
    "resetsAt": "2026-11-01T00:00:00Z"
  }
}

curl -H "Authorization: Bearer $PRICANA_KEY" \
  "https://pricana.io/api/v1/plan"

POST https://your-server.example/…

New changes of the change feed (sent by Pricana)

Pricana posts the next changes of your datasets to your endpoint, in order, up to 100 at a time, as the change feed lists them (type: changes), and a test when you send one from the portal (type: ping). Check the signature before you use the body: HMAC-SHA256 with your endpoint's secret over <t>.<body>, compared with each v1 value. Answer with any 2xx within 10 seconds; anything else is tried again after 1, 5, 15 and 30 minutes, then 1, 2 and every 4 hours, and later changes wait. After 24 hours of failures the endpoint is turned off and your team gets an email.

Parameter

Body, den Pricana schickt: WebhookEvent

{
  "changes": [
    {
      "changes": {
        "price": [
          1499,
          1399
        ]
      },
      "id": 812,
      "item": {
        "currency": null,
        "id": null,
        "site": null,
        "title": null,
        "url": null
      },
      "kind": "NEW",
      "observedAt": "2026-10-06T21:03:00Z",
      "previousPrice": 1499,
      "price": 1399
    }
  ],
  "createdAt": "2026-10-07T09:12:31Z",
  "cursor": 1811,
  "id": "evt_5f1c0b2a9d7e4c3b8a6f0e1d",
  "type": "changes"
}

Antworten

• 200 Received (any 2xx will do; the body is ignored).
• default Anything else (and no answer in 10 seconds): tried again later.