How to Embed a Car Listings Widget on Your Website (No Backend Required)

Not everyone building on top of Encar data wants to write backend code. If you run a dealer site, an import business, or a car-buying blog and want listings on a page, the widgets add-on gives you a browser-side integration: one script tag and a custom HTML element load a grid through XAPI Korea's widget endpoint.

The embed

<script src="https://xapikorea.com/widget.js" async></script>
<xapi-cars pk="pk_live_..." brand="hyundai" limit="4"></xapi-cars>

That's the whole integration. The script registers the <xapi-cars> custom element; the element fetches and renders listings when it is mounted, with no build step or framework required. It fetches again when a recognized filter attribute changes, but it does not poll on a timer. Reload the page or change an attribute when you need a fresh result set. It works the same dropped into a static HTML page, a WordPress template, or a React app.

Getting a widget key

Widget keys are different from the enc_... API keys used for direct API access. They're publishable (pk_live_...) and meant to sit visibly in your page's HTML. Create one from Dashboard → Widgets: pick "Car Listings Grid" or "Search Bar," name it, and list the domains where its listing grid may run (subdomains are covered automatically). You can create up to 10 widget keys per account.

The domain allowlist is checked when an embedded <xapi-cars> grid requests listings. A grid request whose page origin or referrer is outside the allowlist is rejected. The hosted XAPI Korea search-results and car-detail requests opened by widgets do not use that embed-domain check; they authenticate with the same publishable key and count toward its usage. Treat a widget key as public browser configuration, not as a secret server-side credential.

Filtering what shows up

<xapi-cars> supports a focused subset of the search API's filters as HTML attributes: brand, model, year-from, year-to, price-min, price-max, fuel-type and sort. Attribute names use hyphens rather than underscores. limit controls the number of cards from 1 to 12; theme, currency and link-target control presentation and navigation.

<xapi-cars
  pk="pk_live_..."
  brand="hyundai"
  fuel-type="electric"
  year-from="2022"
  limit="8"
></xapi-cars>

Filters such as transmission, car-type, body-style and is-accident-free are not supported by the widget. The available subset is useful when a dealer wants a particular brand shown, or a blog post about electric cars wants a grid filtered to just those.

Where clicks go

By default, clicking a card opens that listing's page on Encar. Add link-target="custom" and cards open XAPI Korea's hosted listing page instead.

A search bar instead of a grid

The other widget type, <xapi-search>, is a brand/model/price search form rather than a results grid:

<script src="https://xapikorea.com/widget.js" async></script>
<xapi-search pk="pk_live_..."></xapi-search>

It's a lighter footprint for a page that just needs a way in (a car-buying guide's homepage, say) rather than an embedded results list. The visible form accepts brand, model and a price range. You can also pin year-from, year-to and fuel-type on the element; those values scope the submitted search without appearing as editable fields. Submitting opens XAPI Korea's hosted results page in a new tab.

Limits

Widgets are a paid €20/month add-on available alongside any API plan. An account can have up to 10 widget keys, and each key includes 50,000 widget endpoint requests per month. A listing-grid load, a hosted search-results request and a hosted car-detail request each count as a request; cache hits count too.

Widget endpoint requests are tracked separately from requests made with an enc_... API key, so widget traffic does not consume the data API's monthly request quota, and data API traffic does not consume a widget key's allowance.

If you'd rather build your own UI against the raw data, the search API post covers the same underlying listings without the pre-built frontend.