README

会议指南API的目标是帮助同步AA会议的信息。它是为会议指南应用程序开发的，但它是非专有的，并鼓励其他系统使用它。

如果您有任何反馈，请在此存储库中提交一个问题。

用法

要在您的服务器上实现API，创建一个脚本来从您的数据库中获取信息，并按照正确的规范格式化它（见下文）。

您的数据不得侵犯任何人的匿名性。会议数据中不应使用姓氏。

您可以使用会议指南JSON Feed验证器测试您的源。一旦准备好，或如果您有任何问题，请参阅如何连接到会议指南。

如果您想分享您的脚本，我们将将其包含在此存储库中，以帮助未来的用户。

规范

预期的JSON文件应包含一个简单的会议数组。这是一个实时JSON源示例。

[
	{
		"name": "Sunday Serenity",
		"slug": "sunday-serenity-14",
		"day": 0,
		"time": "18:00",
		"end_time": "19:30",
		"location": "Alano Club",
		"group": "The Serenity Group",
		"notes": "Ring buzzer. Meeting is on the 2nd floor.",
		"updated": "2014-05-31 14:32:23",
		"url": "https://district123.org/meetings/sunday-serenity",
		"types": [
			"O",
			"T",
			"LGBTQ"
		],
		"address": "123 Main Street",
		"city": "Anytown",
		"state": "CA",
		"postal_code": "98765",
		"country": "US",
		"approximate": "no",
		"entity": "District 123",
		"entity_email": "info@district123.org",
		"entity_location": "Example County, California",
		"entity_logo": "https://district123.org/images/logo.svg",
		"entity_phone": "+1-123-456-7890",
		"entity_url": "https://district123.org",
		"feedback_emails": [
			"meetingupdates@district123.org"
		],
	},
	...
]

表格格式

或者，数据可以以表格格式提供，例如在Google表格中（模板）。第一行应该是标题行，列可以按任何顺序排列。列名应该是JSON键的普通语言版本，例如conference_url变为会议 URL。列名目前必须为英文，但数据可以是任何语言。

字段定义

必填字段

会议列表中可以包含许多字段，但每个列表中只有两个字段是必需的：name和slug。当可选字段不适用于会议时，可以省略。

`name`

名称是必需的字符串。它应该是会议名称，如果可能的话。一些地区使用小组名称，尽管这更含糊。最多255个字符。会议名称的最佳实践

使名称少于64个字符，以免在应用程序中被截断。
不要包含可以包含在列表其他地方的信息，例如日期、时间和类型
避免在名称中使用单词AA和meeting，因为这将是多余的

`slug`

slug是必需的，并且必须对于您的数据集是唯一的。它最好是一个字符串，但整数ID也可以。这是会议的主要键，用于在应用程序中标识会议以及形成书签URL。它应该是URL安全的，不包含空格或特殊字符。最多64个字符，但理想情况下更短。通常它是会议名称的表示。当名称属于多个会议时，可以使用数字来消除歧义，例如sunday-serenity-7。

当使用Google表格时，此字段应称为ID。

时间字段

一些会议是“预约”，没有具体时间。对于每周会议，需要day和time。

注意：会议指南规范仅适用于每周会议。建议使用单独的页面列出每月或非定期会议。

会议指南应用仅显示有日期和时间的会议。TSML UI 在底部显示预约会议。

`日期`

对于非预约会议，日期是必需的，可能是一个整数或整数数组0-6，代表星期日（0）到星期六（6）。

`时间`

对于非预约会议，时间是必需的，是一个HH:MM 24小时制五位字符串。

`结束时间`

结束时间是一个可选的五位字符串，格式为HH:MM 24小时制。当添加会议到用户的日历时，会议指南应用和TSML UI会使用此值（如果存在）。此外，TSML UI会使用此值在顶部显示“会议进行中”横幅。如果省略，则默认为开始时间后一小时。

`时区`

时区是一个可选的字符串，格式为时区数据库格式（例如America/New_York）。在TSML UI中显示不同时区的会议时很有帮助。

地理字段

要列在会议指南应用中，会议还必须包含某些地理信息。这可以是以以下格式

"formatted_address": "4953 W Addison St, Chicago, IL 60641, USA"

或分开成单独的字段

"address": "4953 W Addison St",
"city": "Chicago",
"state": "IL",
"postal_code": "60641",
"country": "US"

请特别注意从地址中去除额外信息，例如“楼上”或“后面”，因为这通常是地理编码问题的根本原因。这些信息属于notes字段，见下文。

在线会议可能有一个大致的地址（例如芝加哥，伊利诺伊州，美国），但面对面会议必须有一个具体的地址。

区域字段

`region`

区域是一个可选的字符串，代表会议位置的地理子集。通常这是一个街区或城市。不鼓励使用区号，因为这需要特殊程序知识才能理解。会议指南导入器会忽略此信息，但TSML UI会使用它。

`sub_region`

当region存在时，可以使用子区域来进一步指定位置。会议指南导入器会忽略此信息，但TSML UI会使用它。

`regions`

可以使用区域和子区域代替，以支持任何数量的分层区域。例如

"regions": ["Illinois", "Chicago", "Wicker Park"]

当使用区域时，最一般的区域首先，最具体的区域最后。顶级区域之间应有差异。例如，一个全州范围的会议查找器，其会议都在伊利诺伊州，不应将伊利诺伊州作为顶级区域。应省略共享所有会议的区域。

当使用Google Sheet时，可以使用>分隔多个区域。

在线会议可能属于地理区域，这表示会议的起源或亲和力，即使其成员可能在地理上更分散。或者，某些网站使用任意区域，如在线。

在线会议字段

在线会议必须有一个conference_url和/或conference_phone字段，才能被视为活跃的。

`conference_url`

会议URL是一个可选的字符串，应该是常见的视频会议服务，如Zoom或Google Hangouts。它应该直接进入会议，而不是链接到中间页面。

`conference_url_notes`

会议URL注释是一个可选的字符串，其中包含有关conference_url的元数据（例如，对于那些不愿发布一键URL的小组，可以包含明文中的会议密码）。

`conference_phone`

会议电话是一个可选的电话号码，用于拨打特定会议。应该是数字，除了可以使用+符号表示国际拨号，还可以使用,、*和#来形成一键电话链接。

`conference_phone_notes`

会议电话备注是一个可选的字符串，包含有关 conference_phone 的元数据（例如会议密码或其他用户说明）。

可选字段

`latitude` 和 `longitude`

纬度和经度是可选的数字值，指示会议的地理位置。这里只需要五位小数的精度（1.11m）。这些值被会议指南导入器忽略，但对于TSML UI很有帮助，它使用这些值来显示会议位置的地图，并推断会议地址不是近似值。

`approximate`

Approximate是一个可选的字符串化布尔值，如果存在，表示地址是一个近似位置（"yes"）或地图上的特定点，例如街道地址（"no"）。此值被会议指南导入器忽略，但由TSML UI在latitude 和 longitude不存在时使用。

`updated`

Updated是一个可选的UTC时间戳，格式为YYYY-MM-DD HH:MM:SS，指示列表上次更新时间。

`group`

Group是一个可选的字符串，表示提供会议的团体名称。团体可以在多个地点举办会议。此值被会议指南导入器忽略，但由TSML UI使用。

`group_notes`

Group Notes是一个可选的长文本字段。换行符是可以的，但HTML将被移除。此值被会议指南导入器忽略，但由TSML UI使用。在导入时，12步会议列表插件将此值应用于具有相同团体名称的所有会议。

此字段不应包含HTML或其他格式。它是纯文本。

`venmo`

Venmo是一个可选的字符串，应该是Venmo用户名，例如 @AAGroupName。这被视为会议第七传统贡献的地址，而不是其他实体。

`square`

Square是一个可选的字符串，应该是Square Cash App cashtag，例如 $AAGroupName。这被视为会议第七传统贡献的地址，而不是其他实体。

`paypal`

PayPal是一个可选的字符串，应该是PayPal.me用户名，例如 AAGroupName。这被视为会议第七传统贡献的地址，而不是其他实体。

`url`

URL是可选的，应该指向区域网站上会议的列表。这由会议指南应用程序使用，但不由TSML UI使用。

`编辑_url`

编辑 URL 是一个可选的字符串 URL，受信任的仆人可以使用它来编辑特定会议的列表。会议指南会忽略这个设置，但 TSML UI 会使用它。

`反馈邮箱`

反馈邮箱是一个数组，包含负责列表的服务实体的反馈地址。当使用 Google 表格时，用 , 分隔多个地址。

`反馈_url`

反馈 URL 是一个可选的字符串 URL，可以用作 feedback_emails 的替代，以提供关于会议的反馈。这些可以是现场或离线的绝对 URL，例如

https://example.org/feedback?meeting=meeting-slug-1
https://typeform.com/to/23904203?meeting=meeting-slug-1
mailto:webservant@domain.org?subject=meeting-slug-1.

服务实体字段

`实体`

实体是负责列表的服务实体的名称。实体信息是可选的，但如果其他实体字段中有任何字段，则必须提供 entity。

`实体邮箱`

实体邮箱是负责列表的服务实体的公共电子邮件地址。这应该是一个单独的电子邮件地址。

`实体位置`

实体位置是对实体服务区域的物理描述，例如 华盛顿州 Whatcom 县。

`实体徽标`

实体徽标是负责列表的服务实体徽标的 URL。它应该以 https:// 开头。理想情况下，这个链接指向的图像是一个基于矢量的 SVG，因此它可以缩放到任何大小。此外，图像应该是方形的，并且具有透明背景。最后，颜色应使用 currentColor 指定，以便它们可以适应应用的颜色模式（浅色、深色）。

`实体电话`

实体电话是负责列表的服务实体的电话号码。应该是格式为 +1-123-456-7890，并以国家代码开始，用于国际拨号。

`实体网站_url`

实体网站 URL 是负责列表的服务实体的网站主页。这应该以 https:// 开头。

联系方式

联系方式是可选的，通常用于会议密度低的地方，用户可能需要联系会议以确认其状态。

联系方式不应破坏任何人的匿名性。联系信息中不应使用姓氏。

contact_1_name 是会议的第一联系人姓名。

contact_1_email 是会议的第一联系人电子邮件地址。

contact_1_phone 是会议的第一联系人电话号码。

contact_2_name 是会议的第二联系人姓名。

contact_2_email 是会议的第二联系人电子邮件地址。

contact_2_phone 是会议的第二联系人电话号码。

contact_3_name 是会议的第三联系人姓名。

contact_3_email 是会议的第三联系人电子邮件地址。

contact_3_phone 是会议的第三联系人电话号码。

常见问题与关注

我们使用不同的会议代码！

没关系。应用用户实际上看不到代码，他们只看到它们所转换的类型。

我们的会议类型没有列出！

类型必须在应用中保持一致，以提供良好的用户体验。通常，用户可能会同时看到来自几个区域的会议结果（这种情况在小区域和边界附近发生）。我们使用的会议类型集是 70 多个区域之间共同同意的一组名称。如果您有修改列表的请求，我们将在我们的指导委员会会议上提出。

会议指南要求

一些应用有关于内容需要包含在源中的要求。例如，会议指南要求 slug、day、time 以及地理信息存在，以便导入。

为什么 slug / ID 是必要的？

Slug是必填的唯一字段，因为有一个应用功能允许用户“收藏”会议，为了使其在不同会话中持续存在，我们必须将其附加到唯一字段。

为什么需要日期和时间？

会议可以“预约”，这在没有很多会议的地方很常见。然而，会议指南应用需要这些信息来向用户展示有用的信息。

为什么在线会议也需要地理信息？

会议指南数据库中有太多的会议，无法向所有用户展示。为了仅展示最相关的信息，会议指南会选择“附近的”会议——即使该会议是在线的。在这些情况下，位置可以被视为会议的起点，或地理亲和力。

对这些会议使用近似位置。`formatted_address` 是这个字段中最灵活的，值可以是诸如：`Wicker Park, Chicago, IL, USA`（邻里），`Chicago, IL, USA`（城市），或`Illinois, USA`（州）。也可以使用`country`，`city`和`state`字段原子性地。

这些位置应该是标准化的（你能在谷歌地图上找到它吗？），并暗示时区。因此，不要使用跨越多个时区的宽泛地理区域，如`United States`。

为什么会议笔记中不能有HTML？

数据应该在各种设备之间具有可移植性，一些设备可能不支持HTML。

关于商务会议或其他每月会议呢？

此API是针对每周恢复会议的。我们建议使用其他方法（单独页面，日历插件）来显示这些类型的会议。

会议类型

以下代码仅用于传输会议数据。应用用户将只能看到完整的定义。

以下代码应被视为“预留”。在你的实现中，你可以更改描述（例如“主题讨论”而不是“讨论”），只要意图相同。例如，“Child Care Available”是“Babysitting Available”的常见替代词。也可以添加类型，导入器会忽略它们，但请注意不要使用任何现有或提议的代码。

此外，在添加自定义类型时，最好远离任何ISO 369语言代码，因为这些代码可能会在未来添加。

提议的新类型

以下类型提议用于未来使用。它们目前不在应用中使用。

提议更改的类型

以下类型正在考虑更改名称。

共享您的数据

如果您选择，您可以通过在您网站的`<HEAD>`中链接到它（如RSS）使您的源可发现。

<link rel="alternate" type="application/json" title="Meetings Feed" href="https://example.com/etc/meetings-feed">

脚本可以有任意名称，也可以在任何目录下，但它应该是完全合格的URL，并且需要`title="Meetings Feed"`属性。

在您的代码中使用规范

PHP

Code4Recovery规范作曲家包

此包包含一个类，可以使最新的会议类型可用于您的应用。

安装

composer require code4recovery/spec

获取所有可用语言

返回一个包含所有可用语言的数组。

$spec::getLanguages();

// this returns:
[
	'en' => 'English',
    'es' => 'Español',
    'fr' => 'Français',
    'ja' => '日本語',
    'sv' => 'Svenska',
    'sk' => 'Slovenčina',
];

获取所有类型

返回一个包含每种语言中类型的对象。

$spec::getAllTypes();

// this returns (truncated):
{
  "11": {
    "en": "11th Step Meditation",
    "es": "Meditación del Paso 11",
    "fr": "Méditation sur la 11e Étape",
    "ja": "ステップ11 黙想",
    "sv": "11th Stegs Meditation",
    "sk": "Meditácia 11. kroku"
  },
   "12x12": {
    "en": "12 Steps & 12 Traditions",
    "es": "12 Pasos y 12 Tradiciones",
    "fr": "12 Étapes et 12 Traditions",
    "ja": "12のステップと12の伝統",
    "sv": "12 Steg & 12 Traditioner",
    "sk": "12 Krokov & 12 Tradícií"
  },
  ...
};

按语言获取类型

返回一个包含翻译成指定语言的类型的数组。传递所需的语言键作为字符串（例如，'en'，'es'，'fr'等）。

$spec::getTypesByLanguage('en');

// returns (truncated):
[
    "11" => "11th Step Meditation"
    "12x12" => "12 Steps & 12 Traditions"
    "A" => "Secular"
    "ABSI" => "As Bill Sees It"
    ...
];

TypeScript / JavaScript

安装

npm i @code4recovery/spec

用法

import { getTypesForLanguage } from '@code4recovery/spec';

const types = getTypesForLanguage('en');

// returns:
{
  "11": "11th Step Meditation",
  "12x12": "12 Steps & 12 Traditions",
  A: "Secular",
  ABSI: "As Bill Sees It",
  ...
}

许可证

Code4Recovery规范在MIT许可证（MIT）下提供。有关更多信息，请参阅许可证文件。

code4recovery / spec

维护者

详细信息

README

用法

规范

表格格式

字段定义

必填字段

name

slug

时间字段

日期

时间

结束时间

时区

地理字段

区域字段

region

sub_region

regions

在线会议字段

conference_url

conference_url_notes

conference_phone

conference_phone_notes

推荐字段

类型

备注

位置

位置备注