feeldb

FeelDB for your website

Give every title an emotional signature

Add film emotions to your site with an origin-bound publishable key. Choose a ready-made widget or build with the SDK.

Publishable keys (pk) belong in browsers. Secret keys (sk) stay on your server.

On your site
The Matrix

The Matrix

1999 · Film

tt0133093

Real data from the FeelDB catalogue · AI estimate · medium confidence

01 /

Choose your path

01 A /

SDK / view-code

Set an explicit IMDb ID on the element, use JavaScript for compact data, or render a PHP badge on your server.

HTML / imdb / pk
<style>feeldb-emotions { display: block; min-height: 244px; }</style>
<script src="https://feeldb.com/sdk/v1/widget.js" data-feeldb-mount="off" defer></script>
<feeldb-emotions imdb="tt0133093" pk="YOUR_PUBLISHABLE_KEY" variant="card" theme="auto" lang="en"></feeldb-emotions>
PHP · Badge::html() →

01 B /

Drop-in script

One script finds the IMDb ID in your page metadata or IMDb link and mounts the widget. No application code needed.

Auto-detect / pk
<script src="https://feeldb.com/sdk/v1/widget.js" data-pk="YOUR_PUBLISHABLE_KEY" data-variant="chips" async></script>

Include a Movie / TVSeries JSON-LD sameAs IMDb URL, an IMDb link, or explicit IMDb metadata. Use data-feeldb-mount on your reserved target.

03 /

Copy a quickstart

Replace YOUR_PUBLISHABLE_KEY with a pk issued for your website origin. Browser examples never contain a secret key.

dropin
<script src="https://feeldb.com/sdk/v1/widget.js" data-pk="YOUR_PUBLISHABLE_KEY" data-variant="chips" async></script>
element
<style>feeldb-emotions { display: block; min-height: 244px; }</style>
<script src="https://feeldb.com/sdk/v1/widget.js" data-feeldb-mount="off" defer></script>
<feeldb-emotions imdb="tt0133093" pk="YOUR_PUBLISHABLE_KEY" variant="card" theme="auto" lang="en"></feeldb-emotions>
javascript
import { FeelDB } from '@feeldb/emotions';

const client = new FeelDB({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  baseUrl: 'https://feeldb.com',
  lang: 'en'
});
const title = await client.emotions('tt0133093');
// Compact payload: t, s, e, u, x. Keep the FeelDB attribution link.
console.log(title);
php
require __DIR__.'/feeldb-php/autoload.php';

use FeelDB\Emotions\Badge;
use FeelDB\Emotions\Client;

// Server only: FEELDB_API_KEY holds your secret key.
$client = new Client(getenv('FEELDB_API_KEY'), [
    'base_url' => 'https://feeldb.com', 'lang' => 'en',
]);
$title = $client->emotions('tt0133093');
if ($title !== null) {
    echo Badge::html($title, ['lang' => 'en', 'theme' => 'auto']);
}
// Optional paid arcs entitlement, server only.
$arc = $client->arc('tt0133093');
curl
# Server only: FEELDB_API_KEY holds your secret key
curl -H "Authorization: Bearer $FEELDB_API_KEY" \
  'https://feeldb.com/api/v1/titles/tt0133093/emotions?lang=en'

# Server only: up to 100 IDs per batch
curl -X POST 'https://feeldb.com/api/v1/emotions/batch' \
  -H "Authorization: Bearer $FEELDB_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"imdb_ids":["tt0133093"],"lang":"en"}'

JavaScript supports pk in browsers and sk on servers. PHP uses a server secret and can render Badge::html(). Download the 1.1.0 archives and verify SHA256SUMS; registry publication is pending.

04 /

Pricing & units

One successfully served title emotion lookup is one unit. A batch counts each returned title; an arc is a separate unit. Cached responses served by the API, including 304, still consume units.

Arcs require an enabled add-on and are billed separately. An arc failure leaves the base emotions intact.

Price per 1 000 units
ProductPrice / 1,000 units
Title emotions0.50 GEL
Emotion arc · optional add-on3.00 GEL

2000 free units per partner each UTC month, used before paid balance. Unused allowance does not roll over.

After the allowance and balance run out, the API returns 402 balance_exhausted. The widget stops for 600 seconds per pk in that tab and keeps the host page usable. After a credit, the server recovers within 60 seconds; an already stopped tab waits for its timer.

Request access below. We register your website origins and send bank-transfer instructions. Your balance is credited after payment is confirmed; access is not activated automatically by this form.

05 /

Reliability & failure log

A missing IMDb ID or mount target, network failure, script error or taxonomy mismatch sends a small best-effort report to our failure log. Reports carry a publishable key and optional title ID, never a secret. Partner admins can inspect aggregated failures. A failed report never interrupts the host page.

Handle stable error codes: 401 key_required / key_revoked, 403 origin_not_allowed / addon_required, 402 balance_exhausted and 429 quota_exceeded. Respect Retry-After; never retry in a tight loop.

Not every title has enough data. Widgets show an honest empty state; unknown, hidden and malformed titles share the same 404. Requests without pk receive uniform 401 when keyless lookup is retired.

06 /

Keep the attribution

The widgets and PHP badge include a visible FeelDB link. Keep that link visible and followable. With a custom interface, use the compact response’s u path on the API origin.

Emotion data: FeelDB
07 /

Questions before you start

Can I expose a publishable key?

Yes. A pk is intended for browser markup and is bound to your registered website origins. Keep sk secret and server-side.

Can I use title lookups without a key?

The legacy keyless title lookup is being retired under SEC-18. When disabled, every ID returns 401 key_required without pk. Taxonomy, icons and OpenAPI remain public; there is no keyless batch or arc.

What does the drop-in script detect?

It reads IMDb metadata, Movie / TVSeries JSON-LD or IMDb links. Reserve a target with data-feeldb-mount for predictable placement. Explicit elements take priority over auto-mount.

Which SDK should I use?

JavaScript supports pk in browsers and sk on servers. PHP uses a server secret and can render Badge::html(). Download the 1.1.0 archives and verify SHA256SUMS; registry publication is pending.

08 /

Let’s connect your catalogue

Tell us about your site and how you plan to use the data. A key gives you more volume and batch access.

Up to 2,000 characters. Do not include keys or other secrets.