Facebook Events / Facebook 活动

Search Facebook Events and read a single event's details.

搜索 Facebook 活动并读取单个活动的详情。

Commands / 命令

Search Events / 搜索活动

facebook-cli events search [--scope <scope>] [--keywords <text>] [--location <place>] [--latitude <lat> --longitude=<lng>] [--radius-in-miles <n>] [--category <category>] [--start-date <YYYY-MM-DD>] [--end-date <YYYY-MM-DD>] [--limit <n>] [--after <cursor>]

Options: / 选项：

• --scope (optional): connected (default) — events you are connected to (going, interested, invited, hosting); discover — popular nearby events from the recommendation backend
• --scope（可选）：connected（默认）——你已关联的活动（将参加、感兴趣、受邀请、主办）；discover——来自推荐后端的热门附近活动
• --keywords (optional): Free-text search, e.g. "music", "farmers market"
• --keywords（可选）：自由文本搜索，例如 "music"、"farmers market"
• --location (optional): Place string, e.g. "Seattle". Discover scope searches near this place instead of your location. The server geocodes it to a city center, so it cannot express a neighborhood or an address
• --location（可选）：地点字符串，例如 "Seattle"。discover 范围会以该地点（而非你的位置）为圆心搜索。服务器会把它地理编码为市中心，因此它无法表达某个街区或具体地址
• --latitude / --longitude (optional, discover scope only): Exact WGS-84 search center. Pass both or neither; one alone is an error. The pair takes precedence over --location. Use this whenever you have real coordinates — it is more accurate than any place string
• --latitude / --longitude（可选，仅限 discover 范围）：精确的 WGS-84 搜索中心。两者都传或都不传；只传一个是错误。这对参数优先于 --location。只要有真实坐标就使用它——它比任何地点字符串都更精确
• --radius-in-miles (optional, needs the coordinate pair): Search radius around the coordinates. Defaults to 25 miles
• --radius-in-miles（可选，需要坐标对）：围绕坐标的搜索半径。默认 25 英里
• --category (optional): Event category name, e.g. MUSIC_AND_AUDIO
• --category（可选）：活动类别名称，例如 MUSIC_AND_AUDIO
• --start-date / --end-date (optional): Calendar dates (YYYY-MM-DD); start must not be after end
• --start-date / --end-date（可选）：日历日期（YYYY-MM-DD）；开始日期不得晚于结束日期
• --limit (optional): Maximum events per page (default 10, max 25)
• --limit（可选）：每页活动数上限（默认 10，最大 25）
• --after (optional): Pagination cursor from the previous response (paging.cursors.after). Cursors are bound to their search scope — do not reuse a cursor with a different scope
• --after（可选）：来自上一次响应的分页游标（paging.cursors.after）。游标与其搜索范围绑定——不要把游标用于不同的范围

Examples: / 示例：

# My upcoming events
facebook-cli events search

# Keyword search across popular nearby events
facebook-cli events search --scope discover --keywords "music" --limit 5

# Events near a place on/after a date (city-center accuracy)
facebook-cli events search --scope discover --location "Seattle" --start-date 2026-07-31 --limit 5

# Events near exact coordinates, within 5 miles (preferred when coordinates are known)
facebook-cli events search --scope discover --latitude 37.5072 --longitude=-122.2605 --radius-in-miles 5 --limit 5

# Next page (pass the cursor from the previous response)
facebook-cli events search --scope discover --keywords "music" --after "<cursor_from_previous_response>"

Choosing a location: / 选择位置：

1. If the turn context already carries the user's coordinates (for example a message_location
   tag), pass them straight to --latitude / --longitude. Do not reverse-geocode them into a
   place name first — that throws away the precision this command exists to use.
2. 如果本轮上下文已带有用户的坐标（例如 message_location 标签），把它们直接传给 --latitude / --longitude。不要先把它们逆地理编码为地名——那样会丢弃本命令专门用来利用的精度。
3. If the user named a place, geocode it with map.geocode and pass the coordinates, or pass the
   place string to --location when city-level accuracy is enough.
4. 如果用户说出了地名，用 map.geocode 对其地理编码并传入坐标；当城市级精度已足够时，也可以把地点字符串传给 --location。
5. If nothing establishes a location, ask the user. Discover scope with no location falls back to
   a server-side guess, and the response never says which place it used.
6. 如果没有任何信息能确定位置，询问用户。无位置的 discover 范围会退回到服务端的猜测，且响应绝不会说明它用的是哪个地点。

Negative coordinates: write --longitude=-122.2605 with the =. A bare --longitude -122.2605
is misread as another flag and fails with error: unexpected argument '-1' found. The same applies
to --latitude in the southern hemisphere.

负坐标： 写 --longitude=-122.2605 时要带 =。裸写的 --longitude -122.2605 会被误读为另一个标志，并报错 error: unexpected argument '-1' found。南半球的 --latitude 同理。

Response fields per event: / 每个活动的响应字段：

• id: Numeric raw event ID (global, not app-scoped — matches the ID in permalink_url)
• id：数字形式的原始活动 ID（全局，非应用范围——与 permalink_url 中的 ID 一致）
• name: Event name
• name：活动名称
• permalink_url: Shareable link, always https://www.facebook.com/events/<id>/
• permalink_url：可分享链接，始终为 https://www.facebook.com/events/<id>/
• description: Event description (may be null)
• description：活动描述（可能为 null）
• start_time / end_time: Timestamps with offset (e.g. 2026-08-01T11:00:00-0400)
• start_time / end_time：带时区偏移的时间戳（例如 2026-08-01T11:00:00-0400）
• location: Venue or address text (may be null)
• location：场馆或地址文本（可能为 null）
• category: Category name (may be null)
• category：类别名称（可能为 null）
• going_count / interested_count: Attendance counts
• going_count / interested_count：出席人数统计
• timezone: IANA timezone (may be null)
• timezone：IANA 时区（可能为 null）
• privacy: public, private, etc. (may be null)
• privacy：public、private 等（可能为 null）
• is_online: Whether the event is online
• is_online：活动是否在线举行
• online_url: Third-party URL where an online event is hosted. Details responses only — search results omit this key entirely rather than sending null
• online_url：在线活动举办所在的第三方 URL。仅详情响应提供——搜索结果会完全省略该键，而不是发送 null

The response is paginated: events live under data, with the next cursor at paging.cursors.after when more pages exist.

响应是分页的：活动位于 data 之下，当还有更多页时，下一页游标位于 paging.cursors.after。

Read Event Details / 读取活动详情

facebook-cli events details --event-id <id>

Options: / 选项：

• --event-id (required): Raw numeric event ID — the id from search results, or the number embedded in the event's permalink_url
• --event-id（必填）：原始数字活动 ID——搜索结果中的 id，或活动 permalink_url 中内嵌的数字

This is the only events route that populates online_url. A malformed ID returns 400; an event that does not exist or is not visible to you returns 404 (the two cases are indistinguishable by design).

这是唯一会填充 online_url 的活动路由。格式错误的 ID 返回 400；不存在或对你不可见的活动返回 404（按设计这两种情况无法区分）。

Examples: / 示例：

# Read one event (ID taken from a search result)
facebook-cli events details --event-id 1679757800076464

Response fields: same as search, plus online_url (null when the event has no third-party online URL).

响应字段： 与搜索相同，外加 online_url（当活动没有第三方在线 URL 时为 null）。