Crafting Event Finder

Count matching events per craft. How many events match a search, per top-level craft, for the 'Jump to a craft' chips. Takes the same filters as GET /api/events (q, type, tag, state, when or from+to, near or lat+lng, radius, free, online, inperson, tz) and counts with every one of them except craft, which is accepted and ignored, so each craft keeps its number while one is chosen. Child crafts count toward their top-level parent (needlepoint, cross-stitch and embroidery count as needlework), and an event counts once per top-level craft, so the crafts can add up to more than `total`, the distinct number of matching events. A craft's count equals the total GET /api/events reports for that craft=<slug>, with one known exception: with a text query (q), the typo-tolerant fallback applies only when a search has no exact text match, so it can apply to the all-crafts count but not to one craft's search (or the other way round) and the numbers can then differ. Only crafts with at least one match are listed, most first, then in taxonomy order. Location is never inferred from the caller's IP; a near that matches no US place is a 400. Answers 503 not_configured while the counts aren't available.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "maxLength": 200
    },
    "craft": {
      "type": "string",
      "maxLength": 400
    },
    "type": {
      "type": "string",
      "maxLength": 200
    },
    "tag": {
      "type": "string",
      "maxLength": 400
    },
    "state": {
      "type": "string",
      "maxLength": 40
    },
    "when": {
      "type": "string",
      "maxLength": 20
    },
    "from": {
      "type": "string",
      "maxLength": 10
    },
    "to": {
      "type": "string",
      "maxLength": 10
    },
    "near": {
      "type": "string",
      "maxLength": 100
    },
    "lat": {
      "type": "string",
      "maxLength": 20
    },
    "lng": {
      "type": "string",
      "maxLength": 20
    },
    "radius": {
      "type": "string",
      "maxLength": 5
    },
    "free": {
      "type": "string",
      "maxLength": 1
    },
    "online": {
      "type": "string",
      "maxLength": 10
    },
    "inperson": {
      "type": "string",
      "maxLength": 10
    },
    "sort": {
      "type": "string",
      "maxLength": 10
    },
    "tz": {
      "type": "string",
      "maxLength": 64
    }
  }
}

Count upcoming events per state. Upcoming published events in the next 12 months, grouped by US state, with each state's most common craft. `by` must be `state`.

{
  "type": "object",
  "properties": {
    "by": {
      "type": "string",
      "const": "state"
    }
  },
  "required": [
    "by"
  ]
}

This site's look: its theme and the season showing today

{
  "type": "object",
  "properties": {}
}

Get one event by slug. One published event with its upcoming dates and its organizer's pictures (`images`, the first is the cover). `owned` says whether an organizer manages it, and `managedBy` names that organizer (their public page's slug, name and picture) when their profile is public. A former slug (the event was renamed when its year or town changed) answers the same event, under its current `slug`. A cancelled event whose dates aren't over yet also answers, with `cancelled` true and no upcoming dates; `scheduleChange` says when a published event is postponed, rescheduled (with `previousStartDate`) or moved online.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    }
  },
  "required": [
    "slug"
  ]
}

Get an event's organizer contact. The contact name, email and phone the organizer published for this event, exactly as they wrote them. 404s when the event has neither a name nor an email/phone. Rate-limited more strictly than other reads (the detail limit), and answers with Cache-Control: no-store and X-Robots-Tag: noindex.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    }
  },
  "required": [
    "slug"
  ]
}

Upcoming event counts by network craft. A daily snapshot (crafting-network/event-demand@1) of how many published events Crafting Event Finder lists in the next 60 days (today to today plus 60, Pacific), per network craft tag from the network manifest, most first then by tag. Each craft gives its label, count (distinct events with a day in the window; a repeating or running event counts once), online (online or hybrid events), earliest (the first day in the window with one) and regions (a count per US state code, with online events as `online`; a hybrid event counts in its state). A child craft rolls up to its parent's tag; an Other crafts event counts under the tags its own words name; craft-fair is never a tag, and an event with no tag is left out. Counts and dates only. The answer never depends on the caller and is recomputed at most once a day.

{
  "type": "object",
  "properties": {}
}

Get an online event's join details. The link, meeting ID, passcode and phone the organizer published for joining online, exactly as they wrote them. Shown only from 30 minutes before the start of the event's next occurrence until it ends: outside that window it answers 403 forbidden with a message saying when the details appear (details.opensAt, an ISO time, when known). 404s when the event has none of these. Rate-limited more strictly than other reads (the detail limit), and answers with Cache-Control: no-store and X-Robots-Tag: noindex.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    }
  },
  "required": [
    "slug"
  ]
}

A withdrawn event's title and status, with events like it. For the address of an event this site no longer lists (hidden, or cancelled and past): its title, whether it was cancelled, and up to 4 upcoming events like it (the same search as /similar). Never its contact, join or owner details. Any other slug (unknown, published, another site's) is a 404. The event page's 404 shows this (WI-094, WI-097).

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "slug"
  ]
}

Get an organizer's public page. An organizer's public profile (name, About, website, town and state, crafts and picture) with their published events on this site: upcoming soonest first (at most 50), then the newest 12 past. Only organizers with a display name have a public page; anyone else is 404.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    }
  },
  "required": [
    "slug"
  ]
}

This site's name and which crafts it covers

{
  "type": "object",
  "properties": {}
}

Craft types, event types and tags used across the site

{
  "type": "object",
  "properties": {}
}

Search upcoming crafting events on this site. Published, upcoming events with their next date in the window. Filters: q (full text with typo tolerance), craft/type/tag (comma lists of taxonomy slugs; a top-level craft also matches its child crafts, so needlework includes cross-stitch), state, when (weekend|next7|next30|next90|month:YYYY-MM) or from+to, near (a US place as 'City, ST', e.g. 'Columbus, OH', or 'all') or lat+lng, radius (25|50|100|250|any, default 100 with a location), free=1, online=1 (only online events; other values are ignored), inperson=1 (only in-person events, including multi-location; other values are ignored; online=1 and inperson=1 together cancel out to no format filter, rather than matching nothing), sort (date|distance|relevance; default best match for q, else soonest first; distance needs a location, and without one falls back to that default), tz (IANA, for date presets). Invalid filter values are ignored, except a near that matches no US place, which is a 400 validation_failed. With no state, near or lat+lng, a trailing US place in q, like 'quilt show Arizona' or 'Phoenix, AZ', sets the location: a state name or capitalized code becomes state and 'City, ST' becomes near (radius 50 unless given; a city that matches no place is retried on its last 2 words, then its last word, then falls back to its state), and the place is removed from the text query. Location is never inferred from the caller's IP. `featured` holds up to 3 featured events matching the same search; they are excluded from `items` on every page. featured=0 turns that off: no featured lookup, `featured` is empty and `items` leaves nothing out (for a client that shows its own results without a featured row).

{
  "type": "object",
  "properties": {
    "limit": {
      "default": 24,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "type": "string",
      "maxLength": 500
    },
    "q": {
      "type": "string",
      "maxLength": 200
    },
    "craft": {
      "type": "string",
      "maxLength": 400
    },
    "type": {
      "type": "string",
      "maxLength": 200
    },
    "tag": {
      "type": "string",
      "maxLength": 400
    },
    "state": {
      "type": "string",
      "maxLength": 40
    },
    "when": {
      "type": "string",
      "maxLength": 20
    },
    "from": {
      "type": "string",
      "maxLength": 10
    },
    "to": {
      "type": "string",
      "maxLength": 10
    },
    "near": {
      "type": "string",
      "maxLength": 100
    },
    "lat": {
      "type": "string",
      "maxLength": 20
    },
    "lng": {
      "type": "string",
      "maxLength": 20
    },
    "radius": {
      "type": "string",
      "maxLength": 5
    },
    "free": {
      "type": "string",
      "maxLength": 1
    },
    "online": {
      "type": "string",
      "maxLength": 10
    },
    "inperson": {
      "type": "string",
      "maxLength": 10
    },
    "sort": {
      "type": "string",
      "maxLength": 10
    },
    "tz": {
      "type": "string",
      "maxLength": 64
    },
    "featured": {
      "description": "0 skips the featured row: `featured` comes back empty and nothing is left out of `items`. Any other value is ignored.",
      "type": "string",
      "maxLength": 10
    }
  }
}

Online event picks to show beside a local search. The Online events band for a local search (a place with a distance, or a state): at most 3 online events anywhere that match the search's words, crafts, types, tags, price and dates, filled from other crafts only when short, each part ranked with a start in the viewer's small hours (10 pm to 7 am in tz) after the rest, then soonest, and the caller's Accept-Language first. Takes the same filters as GET /api/events. `total` and `href` are 'See all online events (N)': /online with the search's top-level crafts and Free only, counted over its next 30 days (the crafts dropped when none has an online event); `matched` is how many picks matched the search's own crafts; `crafts` the search's top-level crafts. Location is never inferred from the caller's IP; a near that matches no US place is a 400.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "maxLength": 200
    },
    "craft": {
      "type": "string",
      "maxLength": 400
    },
    "type": {
      "type": "string",
      "maxLength": 200
    },
    "tag": {
      "type": "string",
      "maxLength": 400
    },
    "state": {
      "type": "string",
      "maxLength": 40
    },
    "when": {
      "type": "string",
      "maxLength": 20
    },
    "from": {
      "type": "string",
      "maxLength": 10
    },
    "to": {
      "type": "string",
      "maxLength": 10
    },
    "near": {
      "type": "string",
      "maxLength": 100
    },
    "lat": {
      "type": "string",
      "maxLength": 20
    },
    "lng": {
      "type": "string",
      "maxLength": 20
    },
    "radius": {
      "type": "string",
      "maxLength": 5
    },
    "free": {
      "type": "string",
      "maxLength": 1
    },
    "online": {
      "type": "string",
      "maxLength": 10
    },
    "inperson": {
      "type": "string",
      "maxLength": 10
    },
    "sort": {
      "type": "string",
      "maxLength": 10
    },
    "tz": {
      "type": "string",
      "maxLength": 64
    }
  }
}

Online events, by day in the viewer's time zone. The /online page: every published online or hybrid event whose next date falls in the next 30 days (from today in tz), filtered by craft, time of day (tod), day, free and language (lang), all judged in the viewer's zone (tz), and grouped by the viewer's own start date. At most 200 events are read; `truncated` says more exist. Time of day and day are worked out per event from its own start time and zone, which is why they live here and not on GET /api/events (online=1 there lists online events by their own dates, paged).

{
  "type": "object",
  "properties": {
    "craft": {
      "description": "Comma list of top-level craft slugs (any of); unknown slugs are ignored.",
      "type": "string",
      "maxLength": 500
    },
    "tod": {
      "description": "Comma list of morning (5 am to noon), afternoon (noon to 5 pm), evening (5 pm to 5 am), judged in tz; an event with no start time never matches one.",
      "type": "string",
      "maxLength": 100
    },
    "day": {
      "description": "today, week (the next 7 days) or weekend (this or the coming Fri to Sun), in tz.",
      "type": "string",
      "maxLength": 20
    },
    "free": {
      "description": "1 for free events only.",
      "type": "string",
      "maxLength": 5
    },
    "lang": {
      "description": "One language code (en, es): only events known to be held in it. Without it every language shows, the caller's Accept-Language ranked first within each day.",
      "type": "string",
      "maxLength": 10
    },
    "tz": {
      "description": "The viewer's IANA time zone; days and times of day are judged in it. Default America/New_York.",
      "type": "string",
      "maxLength": 64
    }
  }
}

Look up US places by name (for location search). Prefix match on US Census places. Accepts 'City' or 'City, ST'. Returns up to 8, largest first.

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 2,
      "maxLength": 60
    }
  },
  "required": [
    "q"
  ]
}

Report an issue with an event listing. Anyone can flag an event as wrong, gone, cancelled, postponed or moved to a new date (rescheduled, with `newStartDate`); an admin reviews every request, none is applied on its own. Browser forms pass Turnstile; programmatic callers send an API key instead.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "kind": {
      "type": "string",
      "enum": [
        "correct",
        "remove",
        "cancelled",
        "postponed",
        "rescheduled"
      ],
      "description": "postponed: new date to come; rescheduled: it has a new date (give it as newStartDate)"
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "contactEmail": {
      "type": "string",
      "maxLength": 254,
      "format": "email",
      "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
    },
    "newStartDate": {
      "description": "For a rescheduled request: the event's new start date",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "website": {
      "type": "string"
    },
    "turnstileToken": {
      "type": "string"
    }
  },
  "required": [
    "slug",
    "kind",
    "message"
  ]
}

Events like this one. Up to 4 upcoming events like this one ("More like this" on the event page), never including the event itself: the same top-level crafts (a craft's child crafts included), or the same event type when the event has no craft; within 100 miles of the event, nearest first (250 miles when that finds fewer than 2); other online events anywhere, soonest first, for an online event; the event's state, soonest first, for an in-person event without a map point; over the next 90 days. An event with neither a craft nor a type gets an empty list. A hidden, cancelled or unknown slug is a 404.

{
  "type": "object",
  "properties": {
    "slug": {
      "type": "string"
    }
  },
  "required": [
    "slug"
  ]
}

Submit an event for review. Goes to the moderation queue. Browser forms pass Turnstile; programmatic callers send an API key instead. A signed-in caller (session or user-scope key) skips Turnstile, is recorded as the submitter, may omit organizer_email (the account email is used), and a trusted submitter's event can publish straight away when auto-approval is on. Anonymous callers must send organizer_email.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "start_date": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "end_date": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "string",
          "const": ""
        }
      ]
    },
    "city": {
      "description": "The town; required unless location_kind is online",
      "type": "string",
      "maxLength": 100
    },
    "state": {
      "description": "A US state name or two-letter code; required unless location_kind is online (then taken from the time zone)",
      "type": "string",
      "maxLength": 40
    },
    "venue": {
      "type": "string",
      "maxLength": 200
    },
    "street_address": {
      "type": "string",
      "maxLength": 200
    },
    "postal_code": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{5}$"
        },
        {
          "type": "string",
          "const": ""
        }
      ]
    },
    "location_kind": {
      "type": "string",
      "enum": [
        "venue",
        "online",
        "hybrid",
        "multi"
      ]
    },
    "timezone": {
      "description": "The event's own clock (IANA, like America/Chicago); required for an online or hybrid event",
      "type": "string",
      "maxLength": 64
    },
    "languages": {
      "description": "The languages the event is held in, as BCP 47 codes (en, es); leave out when unknown",
      "maxItems": 5,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 40
      }
    },
    "hosted_by": {
      "description": "The group or shop hosting an online or hybrid event",
      "type": "string",
      "maxLength": 120
    },
    "craft_types": {
      "default": [],
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 60
      }
    },
    "event_type": {
      "type": "string",
      "maxLength": 40
    },
    "tags": {
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "start_time": {
      "type": "string",
      "maxLength": 8
    },
    "end_time": {
      "type": "string",
      "maxLength": 8
    },
    "is_free": {
      "type": "boolean"
    },
    "price_note": {
      "type": "string",
      "maxLength": 200
    },
    "url": {
      "anyOf": [
        {
          "type": "string",
          "format": "uri"
        },
        {
          "type": "string",
          "const": ""
        }
      ]
    },
    "description": {
      "type": "string",
      "maxLength": 5000
    },
    "join_url": {
      "type": "string",
      "maxLength": 500
    },
    "join_meeting_id": {
      "type": "string",
      "maxLength": 40
    },
    "join_passcode": {
      "type": "string",
      "maxLength": 40
    },
    "join_phone": {
      "type": "string",
      "maxLength": 40
    },
    "contact_name": {
      "type": "string",
      "maxLength": 120
    },
    "contact_email": {
      "type": "string",
      "maxLength": 200
    },
    "organizer_email": {
      "type": "string"
    },
    "website": {
      "type": "string"
    },
    "turnstileToken": {
      "type": "string"
    }
  },
  "required": [
    "title",
    "start_date"
  ]
}