data.cons.fyi

/// A collection of events describing a convention series.
interface Series {
  /// The human-readable name for the convention series.
  name: string;

  /// All instances of the convention series.
  events: Event[];
}


/// A specific instance of a convention.
interface Event {
  /// Unique ID across all events, including events in other series.
  ///
  /// This ID should also remain stable.
  ///
  /// It should include the convention name, e.g. `rainfurrest-2016`.
  id: string;

  /// The human-readable name of the convention instance, e.g.
  /// "RainFurrest 2016".
  ///
  /// This should be the well known name of the event, even if the locale the
  /// event is in has a different localized name. For example "Infurnity" should
  /// be preferred over "獸無限". However, "你好兽聚" is preferred over
  /// "Hi Furry" as the Chinese name is more well known.
  ///
  /// In general:
  /// - zh-CN, ru: Prefer the local name, add an en translation.
  /// - zh-TW, zh-HK: Prefer the English name, add a zh-Hant translation.
  /// - ja: Can go either way, refer to the event's marketing material.
  name: string;

  /// Link to the convention website.
  url: string;

  /// The start date of the convention instance.
  ///
  /// Should be in ISO 8601 yyyy-MM-dd format.
  startDate: string;

  /// The end date of the convention instance, inclusive.
  ///
  /// Should be in ISO 8601 yyyy-MM-dd format.
  endDate: string;

  /// The human-readable name of the venue.
  ///
  /// This should be in the locale of the event.
  venue: string;

  /// The human-readable address of the venue, if it is a physical venue.
  ///
  /// The granularity of this is not specified, it does not need to be exact. It
  /// should include the name of the country.
  ///
  /// This should be in the locale of the event.
  address?: string;

  /// The locale of the convention as a Unicode locale identifier, e.g. "en-US".
  locale: string;

  /// Translations for human-readable fields in different locales.
  ///
  /// The translation may contain an entry for the same locale as the event if a
  /// viewer who has that locale set should see a more locale-specific version
  /// of the text.
  ///
  /// For instance, "Kemono Square" is the well known name for the event, but
  /// Japanese viewers may prefer to see "ケモノスクエア" instead.
  translations?: {
    [locale: string]: {
      name?: string;
      venue?: string;
      address?: string;
    };
  };

  /// The GPS coordinates of the venue in WGS-84.
  ///
  /// This may be unset for e.g. virtual conventions.
  ///
  /// Note some services may return coordinates inside China in GCJ-02. Please
  /// make sure to convert them first!
  latLng?: [number, number];

  /// If the convention instance has been canceled.
  canceled?: boolean;

  /// The number of attendees for historical cons.
  attendance?: number;

  /// Sources this data is from.
  sources?: string[];
}

/// A materialized version of Series.
interface MaterializedSeries extends Series {
  /// All instances of the convention.
  events: MaterializedEvent[];
}

/// A materialized version of Event.
///
/// If the event's locale is zh-{CN,TW,HK,MO}, or contains zh-{Hans,Hant}
/// translations, a conversion for the counterpart writing system will
/// automatically be generated.
interface MaterializedEvent extends Event {
  /// The ID of the series this corresponds to.
  ///
  /// This ID may not necessarily remain stable and consumers should not store
  /// it permanently, and should only use it to cross-reference a Series record.
  seriesId: string;

  /// The IANA timezone ID.
  timezone?: string;

  /// The attendance of the previous event in the series.
  previousAttendance?: number;
}