# Deploying and Rendering Recommendations

Source: https://dev.arcxp.com/content-recommendations/content-recommendations-rendering-story-cards/

Turn a single Compass recommendations call into rendered story cards, with empty and error handling.

**Audience:** Front-end developers and product owners integrating Arc XP recommendations into a website, app, or email program.

**Stack used in examples:** TypeScript + React.

This guide is the reusable foundation for every recommendation surface: how a single recommendations call returns display-ready cards, and how to render one card (and one graceful component) well. For where to deploy recommendations and what each placement is good at, see the [Recommendation Surfaces Playbook](https://dev.arcxp.com/content-recommendations/content-recommendations-recommendation-surfaces/). Every surface renders its cards the way this guide describes, so build the rendering component once and reuse it everywhere.

## Rendering recommendations

The Recommendations API returns a **ranked list of recommendations**, each carrying a `card` object with display fields sourced from the underlying content document. There is no separate inflation call: one round trip gives you everything needed to render story cards.

1. **Recommend** — call `GET /experiences/recommend/v1/recommendations` to get a ranked list of items, each with a `card`.
2. **Render** — map each `card` onto a card component.

This part walks through each step, gives you a runnable TypeScript + React snippet, and shows how to handle empty results and error states gracefully.

### Prerequisites

- A site you can issue requests for (you’ll need its `site_id`).
- A way to identify the current viewer (you’ll pass that as `user_id` — anonymous IDs are fine, as long as they’re stable per visitor). See [User ID Guidance](https://dev.arcxp.com/content-recommendations/content-recommendations-item-id-guidance/#user-id).
- An HTTP client. The examples use `fetch`; any client is fine.

### Step 1: Fetch recommendations

#### Endpoint

```
GET https://{org}-config-prod.api.arc-cdn.net/experiences/recommend/v1/recommendations
```

#### Query parameters

Pass `site_id` and `user_id` on every request. For every query parameter, including `num_results`, `subscription_tier`, `section`, and `content_type`, see [Query Parameters](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#query-parameters) in the API reference.

The `section` and `content_type` filters are how each surface in the [Recommendation Surfaces Playbook](https://dev.arcxp.com/content-recommendations/content-recommendations-recommendation-surfaces/) keeps sectional and format-specific placements on-topic. For the full reference — matching rules and additional examples — see [Compass API filters](https://dev.arcxp.com/content-recommendations/content-recommendations-editorial-signals/#pre-personalization-filters).

#### Response shape

The response is a `recommendations` array in display order, plus a response-level `attribution` object and a `locale`. Each item carries `item_id`, `score`, `position`, `attribution_id`, and a `card` with its display fields, or `card: null` when no matching content document exists. For the full schema and an example, see [Response](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#response) in the API reference.

Keep `attribution.exposure_id` and each item’s `attribution_id`: exposure and click events echo them verbatim so analytics can credit the recommendation. `card.thumbnail_url` is a ready-to-use, feed-card-sized image that is safe to render directly. See [Card images](#card-images) for its size, freshness, and fallback behavior.

#### TypeScript example

```ts
type ItemCard = {
    title: string | null;
    date: string | null;
    author: string | null;
    type: "article" | "video" | "podcast" | null;
    is_premium: boolean | null;
    categories: string[];
    tags: string[];
    url: string | null;
    thumbnail_url: string | null;
};

type ScoredItem = {
    item_id: string;
    score: number;
    card: ItemCard | null;
    position: number;
    attribution_id: string;
};

type RecommendationResponse = {
    recommendations: ScoredItem[];
    attribution: { exposure_id: string; issued_at: string; surface_id?: string | null };
    locale: string;
};

// A headless token in your org's experiences key collection. It can only read, so it may ship in page JavaScript.
const COMPASS_API_KEY = "<experiences token>";

async function fetchRecommendations(params: {
    org: string;
    siteId: string;
    userId: string;
    numResults?: number;
}): Promise<ScoredItem[]> {
    const url = new URL(`https://${params.org}-config-prod.api.arc-cdn.net/experiences/recommend/v1/recommendations`);
    url.searchParams.set("site_id", params.siteId);
    url.searchParams.set("user_id", params.userId);
    if (params.numResults) {
        url.searchParams.set("num_results", String(params.numResults));
    }

    const response = await fetch(url, {
        headers: { Accept: "application/json", "X-API-Key": COMPASS_API_KEY },
    });

    if (!response.ok) {
        throw new Error(`Recommendations request failed: ${response.status}`);
    }

    const body = (await response.json()) as RecommendationResponse;
    return body.recommendations;
}
```

### Step 2: Map to card fields

A usable story card needs four fields at minimum:

| Card field | Source field        | Notes                                                                                                                                |
| ---------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Headline   | card.title          | Display title for the card.                                                                                                          |
| Image      | card.thumbnail\_url | Feed-card-sized image, already resized (JPEG, within 640×640), with a fallback to the source image. See [Card images](#card-images). |
| URL        | card.url            | The link the card navigates to on click.                                                                                             |
| Byline     | card.author         | Author display string. Fall back to publication name if absent.                                                                      |

Anything beyond those four (kicker, `card.date`, section label, premium badge from `card.is_premium`) is layered on top of this minimum set. Build cards that degrade gracefully when an optional field is missing, and skip rendering when `card` is `null` or the required fields are missing.

```tsx
type StoryCardProps = {
    item: ScoredItem;
};

function StoryCard({ item }: StoryCardProps) {
    const card = item.card;
    if (!card || !card.url || !card.title) {
        return null;
    }
    return (
        <a href={card.url} className="story-card">
            {card.thumbnail_url ? <img src={card.thumbnail_url} alt="" /> : null}
            <h3>{card.title}</h3>
            {card.author ? <p className="byline">{card.author}</p> : null}
        </a>
    );
}
```

#### Card images

When you ingest a content item, you supply a source image as `thumbnail_url` on the content payload (see [the content endpoint](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/#content-endpoint)). Arc XP generates a **single feed-card-sized derivative** from that source image once, at ingest time. There is one derivative per content item, shared across every site and recommendation surface that renders the item. The derivative is what you receive as `card.thumbnail_url` on recommendation responses and on the Catch-Up Card — no separate image call or hydration step is needed.

- **Format:** JPEG.
- **Size:** fitted within **640×640** pixels, preserving the source image’s aspect ratio. The image is scaled down to fit the box; it is not cropped or padded to a fixed square. Because it arrives already resized, you generally do **not** need to resize it again before rendering it into a card.
- **Freshness:** the derivative is regenerated only when the item’s **source image URL changes**. Re-publishing an item with the same `thumbnail_url` reuses the existing derivative, so change the source image URL when you need a new image to take effect.
- **Fallback:** when a derivative hasn’t been generated yet, or generation didn’t complete, `card.thumbnail_url` falls back to the **original source image URL** you supplied. Image generation never blocks or delays ingestion, so a newly published item is immediately renderable with its source image while its derivative is prepared.

`card` is `null` (and therefore has no image) only when no matching content document is found — for example, an editor-pinned item that hasn’t synced yet.

### Handling empty results and errors

There are three states to design for. **Don’t render a half-broken card grid in any of them.**

| State         | When it happens                                                                               | Recommended UI                                                              |
| ------------- | --------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Empty         | The API returns recommendations: \[\]. Common for new sites, new users, cold-start scenarios. | Show a fallback rail (editorial picks, most-read) — never an empty grid.    |
| Network error | The recommendations request fails (timeout, 5xx, network).                                    | Show the same fallback rail. Log the error for observability.               |
| Validation    | The API returns 422\. Almost always a caller bug (missing/invalid params).                    | Surface during development. In production, treat as the network-error case. |

```tsx
function RecommendationsRail({ org, siteId, userId }: { org: string; siteId: string; userId: string }) {
    const [items, setItems] = useState<ScoredItem[] | null>(null);
    const [error, setError] = useState<Error | null>(null);

    useEffect(() => {
        let cancelled = false;
        (async () => {
            try {
                const scored = await fetchRecommendations({ org, siteId, userId, numResults: 8 });
                if (!cancelled) setItems(scored);
            } catch (e) {
                if (!cancelled) setError(e as Error);
            }
        })();
        return () => {
            cancelled = true;
        };
    }, [org, siteId, userId]);

    if (error) return <EditorialFallbackRail />;
    if (items === null) return <RailSkeleton />;
    if (items.length === 0) return <EditorialFallbackRail />;

    return (
        <div className="recommendations-rail">
            {items.map((item) => (
                <StoryCard key={item.item_id} item={item} />
            ))}
        </div>
    );
}
```

### Checklist before shipping

- You’re passing a stable `user_id` per visitor (not a per-page-load random value) — see [User ID Guidance](https://dev.arcxp.com/content-recommendations/content-recommendations-item-id-guidance/#user-id).
- You’re requesting an appropriate `num_results` for the surface (don’t fetch 50 to render 4).
- You have a fallback rail for empty results.
- You have a fallback rail for network/validation errors.
- Cards render with only the four required fields, even when optional fields are missing.
- Recommendations with `card === null` or missing required fields are skipped (or routed to a placeholder).

## Recommendation surfaces

Where to deploy recommendations, what each placement is good at, and the order to roll them out in are covered in the [Recommendation Surfaces Playbook](https://dev.arcxp.com/content-recommendations/content-recommendations-recommendation-surfaces/). Every surface in it renders its cards the way this guide describes.

## Related documentation

- [Recommendation Surfaces Playbook](https://dev.arcxp.com/content-recommendations/content-recommendations-recommendation-surfaces/) — where to deploy recommendations, what each placement is good at, and the order to roll them out in.
- [Compass API Reference](https://dev.arcxp.com/content-recommendations/content-recommendations-api-reference/) — interactive Swagger for the Collector and Recommendations APIs.
- [Compass API Developer Guide](https://dev.arcxp.com/content-recommendations/content-recommendations-api-developer-guide/) — endpoints, authentication and token provisioning, event schemas, and onboarding guidance.
- [Compass API filters](https://dev.arcxp.com/content-recommendations/content-recommendations-editorial-signals/#pre-personalization-filters) — scoping recommendations by section or content type: query parameters, matching rules, and examples.
- Arc XP PageBuilder Engine sites: [Set up the Compass recommendations block in PageBuilder Editor](https://dev.arcxp.com/content-recommendations/content-recommendations-pagebuilder-setup-guide/) — adding and configuring the recommendations block.
