Docs

Use casesFamily assistants

Family assistants that get Saturday right.

Give your agent real, current things to do for a child's age, a budget and a day. Every listing is confirmed at its source.

Real Philadelphia listings in every example · as of Oct 13

/search · /events · age · free · occurrences=expand · verified_at

what can we do Saturday morning with a 3-year-old? under $15

Three on Saturday, Oct 17, all under $15:

  • Sensory Jump9:00 AM · Funzilla, Fairless Hills · $12 · ages 1–3verified Oct 9
  • Stories of Science10:00 AM · Science History Institute · free · ages not statedverified Sep 26
  • Read, Baby, Read Baby Storytime11:00 AM · Free Library, Cottman Ave · free · ages 0–4weekly

Links go to each organizer's page

does the baby storytime happen every week?

Yes, every Saturday at 11:00 AM. The next four:

  • Oct 17
  • Oct 24
  • Oct 31
  • Nov 7
GET /v1/philadelphia/events?from=2026-10-17&to=2026-10-17&age=3&max_price=15&start_before=12:00&occurrences=expandReal listings · Oct 13

The problem

A wrong answer costs a family a morning.

  • Models guess.Ask a model about this weekend and it fills gaps with plausible dates.
  • Pages drift.Times move, sessions sell out and series end after the page was read.
  • Formats vary.Ages, prices and times are written a hundred ways across venues.

How to build it

Three calls from question to answer.

  1. Read the question as a search

    Send the parent's words as q. Ages in the text become an age filter, and meta.interpreted shows how it was read.

    Try it in the playground
    GET/v1/philadelphia/search?q=toddler+story+timeSample from the API reference
    {
      "data": [
        {
          "type": "event",
          "id": "b81a95d2-1d4e-46fd-9cff-322a41e429ad",
          "slug": "toddler-storytime",
          "name": "Toddler Storytime",
          "snippet": "Stories and songs for children ages 2–5.",
          "match": "all_terms",
          "starts_local": "2026-10-03T10:00:00"
        }
      ],
      "meta": {
        "query": "toddler story time",
        "interpreted": {
          "age": {
            "min": 1,
            "max": 3,
            "from": "toddlers"
          }
        },
        "match_counts": {
          "all_terms": 1,
          "related": 0,
          "partial": 14
        },
        "has_more": false
      }
    }
  2. Narrow it with real filters

    Use /events for the exact answer: an age in years, free or max_price, a from/to date window and weekday.

    Try it in the playground
    GET/v1/philadelphia/events?from=2026-10-17&to=2026-10-17&age=3&max_price=15&limit=1Snapshot, Oct 13
    {
      "data": [
        {
          "id": "c067f382-0734-4fb9-b76b-e19b40085c80",
          "type": "event",
          "name": "Sensory Jump",
          "starts_local": "2026-10-17T09:00:00",
          "has_time": true,
          "timezone": "America/New_York",
          "is_recurring": true,
          "rrule": "FREQ=WEEKLY;BYDAY=SA",
          "place": {
            "name": "Funzilla"
          },
          "price": {
            "min": 12,
            "max": 12,
            "unit": "per_session",
            "is_free": false
          },
          "ages": {
            "min": 1,
            "max": 3,
            "bands": [
              "baby",
              "toddler"
            ]
          },
          "registration_url": "https://www.funzillapa.com/hours-calendar-fun-adventure-park-funzilla-fairless-hills-pa/",
          "confidence": 0.848,
          "verified_at": "2026-10-10T03:03:06.395Z"
        }
      ],
      "meta": {
        "limit": 1,
        "has_more": true
      }
    }
  3. Answer "every week?" with real dates

    With occurrences=expand, a recurring series comes back once per date in your window, each with its own occurrence.

    Try it in the playground
    GET/v1/philadelphia/events?from=2026-10-17&to=2026-10-24&weekday=saturday&age=3&occurrences=expandSnapshot, trimmed
    {
      "data": [
        {
          "id": "ac6b9f2c-1d36-4604-9503-80d30cd2d359",
          "name": "Read, Baby, Read Baby Storytime",
          "occurrence": {
            "starts_local": "2026-10-17T11:00:00",
            "starts_at": "2026-10-17T15:00:00.000Z",
            "index": 4
          }
        },
        {
          "id": "ac6b9f2c-1d36-4604-9503-80d30cd2d359",
          "name": "Read, Baby, Read Baby Storytime",
          "occurrence": {
            "starts_local": "2026-10-24T11:00:00",
            "starts_at": "2026-10-24T15:00:00.000Z",
            "index": 5
          }
        }
      ],
      "meta": {
        "has_more": true
      }
    }

Key fields

The fields your agent should read.

ages.min / ages.max
Ages as numbers. A missing bound is open, so a listing that states no ages still matches every age.
price.is_free, price.min
Free or a real number, never a phrase to parse. Filter with free or max_price.
starts_local, has_time
Local wall-clock time in the metro's timezone. has_time: false means no time was stated, so none is made up.
is_recurring, rrule
Tells a weekly story time from a one-off. Expand it with occurrences=expand.
verified_at
When the source page last confirmed this listing. Show it, or use it to phrase how sure you are.
confidence
Event lists leave out rows below 0.7 by default, so what you get is ready to say out loud.
meta.interpreted
How a natural-language q was read, such as "toddlers" becoming ages 1 to 3.
registration_url
Where to send the parent to book. Link to it rather than paraphrasing terms.

Examples

Prompts it can answer today.

Rainy day

it's raining Sunday, anything indoors for a 4-year-old under $20?

  • Toddler Time9:00 AM · Funzilla · $15 · ages 1–5
  • Sunday Family FUN Skate3:00 PM · Millennium Skate World · $12 · ages not stated
/events?from=2026-10-18&to=2026-10-18&age=4&max_price=20&indoor=true

Close to home

free things in Center City this weekend

  • Stories of ScienceSat, Oct 17 · 10:00 AM · Science History Institute
  • Family Fun Day with PopUpPlaySun, Oct 18 · 1:00 PM · Spruce Street Harbor Park
/events?neighborhood=center-city&from=2026-10-17&to=2026-10-18&free=true

Still on?

is Saturday's Sensory Jump still on?

  • Sensory JumpConfirmed at the source Oct 9. Next: Sat, Oct 17 · 9:00 AM
/v1/events/c067f382-0734-4fb9-b76b-e19b40085c80

FAQ

Questions builders ask.

What happens when a source stops confirming a listing?

It leaves your results until it is confirmed again. Your agent never has to explain a listing that may be stale.

What if a listing does not state ages?

Both bounds come back null, and an age filter keeps it, because unknown is not the same as "not for your child". Say "ages not stated".

Can my agent link to the source?

Yes, with the include=source add-on, which adds the source page URL to each listing. It is enabled per key.

Do recurring events show their next date?

Without expansion, an event keeps its first stated occurrence and carries the next live one under occurrence. With occurrences=expand, you get every date in the window.

Which cities are live?

Philadelphia is live. More cities open as demand builds; vote for yours.

Do I need a key to try it?

No. The playground shows sample responses without a key. Live requests need one; see the quickstart in the docs.

Give your assistant the neighborhood.

Try the requests above with sample data, then get a key from the quickstart.