Store finder render service API

The render service turns a store finder page into HTML on the server. A web server, a CDN or a plugin asks for that HTML and puts it into its own page, so the stores are in the page before any JavaScript runs.

This document is the contract for anyone who calls the service. For a step by step setup on a web server, see the guides in integration/.

At a glance

Base URL:

https://uberall.com/api/locator-fragments

A trailing slash on the endpoint path is accepted: /body/ works the same as /body. Any other path answers 404 not found.

Which endpoint to use

• From your own code (PHP, Node.js, a CMS plugin, a serverless function): call GET /page. One call returns the body and the head from the same render, as JSON. Put body into the store finder's div and head into the page's <head>.
• From a web server that inserts the answer as it is, such as Apache or nginx includes, Varnish ESI or LiteSpeed: call GET /body and GET /head. They return plain HTML, which the server puts in place without reading it.

Authentication

Every call sends the render token in a header:

x-uberall-render-token: YOUR_RENDER_TOKEN

Uberall gives you the token. The locator key is not a secret, since it is in the store finder snippet on every page, so the token is what lets a caller in.

Without the token, or with one the service does not know, the answer is still a 200 with an empty fragment and the reason unauthorised. See Empty answers.

Query parameters

All three endpoints take the same parameters.

path comes last

A web server often pastes the visitor's request into path as it is, without encoding it. If the visitor's URL has an &, it would then set one of the parameters above. So the service reads everything after the first path= as the path, and only what comes before it as the other parameters.

/body?key=YOUR_LOCATOR_KEY&lang=de&path=/store-locator/berlin?q=a&b=c
      └─────── parameters ───────┘ └───────────── path ─────────────┘

When key, lang, widgetOriginUrl or debug appears after path:

• In the path itself, such as path=/store-locator&key=…, the answer is empty with the reason misplaced-parameter. Move the parameter before path.
• In the visitor's query, such as path=/store-locator?lang=fr, it belongs to the site, so the service ignores it.

path may be encoded or not.

Which page is rendered

The path has to be under the store finder's address (widgetOriginUrl). The store finder decides which page it is, the same way it does in the browser: the store finder home, a country, a city, a single store, and so on. A path that is not a page of this store finder gets an empty answer.

The visitor's query (after ?) does not change the HTML. A search or a filter only changes what one visitor sees, and the store finder applies it in the browser, on top of the HTML.

The snippet and the calls must match

The store finder only takes over the server's HTML when it was rendered with the same settings as the snippet on the page. Otherwise it drops the server render and renders in the browser, and search engines and AI assistants may not see your stores.

Leave data-baseurl out of the snippet. The server always renders with Uberall's own API, so a snippet with its own data-baseurl never matches.

GET /page

Everything one render produces, as JSON. For a caller that builds the page itself, such as a plugin. Calling /body and /head costs two renders; /page costs one.

curl -H 'x-uberall-render-token: YOUR_RENDER_TOKEN' \
  'https://uberall.com/api/locator-fragments/page?key=YOUR_LOCATOR_KEY&path=/store-locator/berlin'

HTTP/1.1 200 OK
content-type: application/json
cache-control: public, max-age=300
x-sf-request-id: 0b9a6c4d-3e2f-4a1b-8c7d-5e6f7a8b9c0d
x-sf-widget-version: 3.250.0@abc12345

{
  "body": "<div …>…the store finder markup…</div>",
  "head": "<title>…</title><link rel=\"canonical\" href=\"…\"><meta name=\"description\" content=\"…\">…",
  "page": "locationPage"
}

When there is nothing to render

The status is still 200, with the same headers as an empty /body: x-sf-empty-reason, x-sf-request-id and cache-control: public, max-age=10. The body has the reason:

{ "reason": "unknown-locator" }

With debug=1, a reason that comes from the render (incomplete-render, no-page-content) also carries what the render reported:

{ "reason": "incomplete-render", "errors": ["…"], "warnings": ["no-page-content"] }

GET /body

The store finder markup, to put where the store finder snippet is on the page.

curl -H 'x-uberall-render-token: YOUR_RENDER_TOKEN' \
  'https://uberall.com/api/locator-fragments/body?key=YOUR_LOCATOR_KEY&path=/store-locator/berlin'

HTTP/1.1 200 OK
content-type: text/html; charset=utf-8
cache-control: public, max-age=300
x-sf-request-id: 2f1c5a0e-8a51-4c3e-9d0b-6a2b6a9f1e7d
x-sf-widget-version: 3.250.0@abc12345

<div …>…the store finder markup…</div>

Put the whole answer where the snippet is, as it comes.

GET /head

The tags the page needs in its <head>: title, canonical link, meta tags and the store finder's stylesheet.

curl -H 'x-uberall-render-token: YOUR_RENDER_TOKEN' \
  'https://uberall.com/api/locator-fragments/head?key=YOUR_LOCATOR_KEY&path=/store-locator/berlin'

HTTP/1.1 200 OK
content-type: text/html; charset=utf-8
cache-control: public, max-age=300
x-sf-request-id: 7d0e3b8c-1f4a-4b6e-a2c9-3e5d8f0a1b2c
x-sf-widget-version: 3.250.0@abc12345

<title>…</title><link rel="canonical" href="…"><meta name="description" content="…">…

Put the whole answer into <head>, as it comes.

Response headers

An empty answer is cached for a much shorter time on purpose. A short failure, cached as long as a page, would remove the page's HTML for five minutes without anyone noticing, because the store finder still shows the page to visitors in the browser.

Empty answers

/body, /head and /page always answer with status 200, also when there is nothing to render.

A server side include cannot change the status of the page it is in, and neither Apache nor Varnish has a way to catch an error from one. With another status, the customer's server could not handle it, and some setups would put the error page into the customer's page. So an empty answer is how the service says "nothing to render", and the store finder renders the page in the browser as it did before.

incomplete-render and no-page-content are answered empty on purpose: a page with a part missing would be cached and look fine from outside, which is worse than no HTML at all.

The body of an empty answer:

• /body and /head: an HTML comment with the reason and the request ID, such as <!-- uberall-render: no fragment · reason=unknown-locator · req=… -->
• /page: { "reason": "…" }, see When there is nothing to render

Debugging

With debug=1, an empty /body or /head shows a visible box on the page instead of the HTML comment. It names the reason, explains it in one line, and gives the request ID.

/page adds the render's errors and warnings the same way, see When there is nothing to render.