Skip to content
tailendAPI
OpenAPIGet an API key

Work with responses

Shaping responses

Trim or extend what comes back with fields=, expand= and include=.

View as Markdown

The default response for every event, class, camp and place is lean. Four parameters change what comes back:

cURL
curl -H "X-API-Key: $TAILEND_API_KEY" --get https://api.tailend.dev/v1/philadelphia/events \
  --data-urlencode "fields=name,place.name,price.is_free" \
  --data-urlencode "expand=place" \
  --data-urlencode "include=source" \
  --data-urlencode "include_mode=lenient"
ParameterWhat it does
fields=Comma list of dotted paths to keep (name,place.name). id and type are always kept.
expand=place,organizationAttaches the full Place/Organization object under expanded, instead of just the reference.
include=sourceA paid add-on. Attaches source: {url, crawled_at, verification} to each item. Requires an entitled key.
include=forecastA paid event add-on. Adds a short outlook for eligible timed US events starting within seven days. Requires an entitled key.
include=relatedA paid add-on on the single read of an event, class or camp. Adds related: {similar, from_organization, at_place}. 400 anywhere else. Requires an entitled key.
include_mode=lenientChanges what happens when include= names something your key isn't entitled to: see below.

fields= and expand= compose: fields=expanded.place.name works once you've expanded place.

When your key isn't entitled

include= add-ons require a key entitled to them (see Plans & access). Without one, the request fails:

JSON
{ "error": { "code": "include_not_permitted", "message": "include=source is not available on this key's plan; retry without it, or add include_mode=lenient", "details": { "include": "source" }, "request_id": "req_2c6a19f8d0b34e77" } }

Add include_mode=lenient and the same request succeeds instead: 200, with the block left off and the omission recorded in notices[]:

JSON
{ "data": [ "…" ], "meta": { "…": "…" }, "notices": [ { "code": "include_not_permitted", "include": "source", "message": "…" } ] }

A 200 in lenient mode doesn't mean you got everything you asked for: always check notices[].

The "more like this" rows for a listing page, in one request:

  • similar: nearby listings of the same kind in the same Monday-to-Sunday week as this listing's date, in a matching category and for overlapping ages. Never this listing, its series, its organization or its place.
  • from_organization: the organization's next upcoming listings of the same type, one card per series.
  • at_place: other listings at the same place in the same week.

Up to six cards each. Every card carries id, slug, type, name, the relevant occurrence (starts_at, ends_at, and the local dates starts_on, ends_on), place, image_url, price and is_free. A related card is always something the list endpoints would also return to your key. If a list cannot be produced it comes back empty with a related_unavailable notice; the listing itself is still returned.

Forecasts: include=forecast

Forecasts use degrees Fahrenheit and miles per hour.

  • Events within 48 hours receive hourly periods covering their start-to-end window; when no end is stated, the window is two hours.
  • Later events, up to seven days out, get a summary of the event's local calendar day.
  • Events without a time, coordinates, a US location, or a start within seven days omit forecast.
  • When forecasts are temporarily unavailable the block is omitted and notices[] carries forecast_unavailable.