Feed

  • A Feed entity represents a single active or upcoming stream of CDF data files for a specific country and feed type and is only used in metadata feeds.

  • A single FeedDeliveryReport can contain multiple Feed entities for a given country and feed type, provided their scopes do not overlap geographically, by timeframe, or office level.

  • Feeds can have a limited duration with an expected end date or be "evergreen" with no expected end date and continual refreshing.

  • Feeds should not be removed from the metadata feed until 60 days after the FeedInactiveDate.

A Feed entity represents a single active or upcoming stream of CDF data files over time that correspond to a specific country and CDF feed type. For more details, see Feed types. A FeedDeliveryReport can contain multiple Feed entities for a given country and feed type, as long as their scopes don't overlap, either by geographical scope, timeframe, or office level. The following are examples of valid combinations:

  • A single FeedDeliveryReport can contain both a US officeholders Feed and a US pre-election Feed (evergreen).
  • A single FeedDeliveryReport can contain a US pre-election Feed (2022) and a US pre-election Feed (2024).
  • A single FeedDeliveryReport can contain a US pre-election Feed (2022 Federal-Level Only) and contain a US pre-election Feed (2022 State-Level Only).
  • A single FeedDeliveryReport can contain a US officeholder Feed and a JP pre-election Feed (2022 National-Level Only), but only if both countries are in scope.

A Feed either has a limited duration, because there's an expected end date (such as 60 days after an election), or it's "evergreen," which means that there's no expected end date and it's continually refreshed.

Wait until 60 days after the FeedInactiveDate of a feed before removing it from the metadata feed.

Elements

Element Multiplicity Type Description
FeedId 1 string A unique and stable identifier for the lifetime of the feed. Non-reusable across feeds.
FeedName 1 string A short description for the feed, such as "US Officeholders 2023".
FeedType 1 FeedType Indicates which type of CDF feed this is.
FeedLongevity 1 FeedLongevity Indicates the lifespan of the feed.
SourceDirPath 0 or 1 FeedSourcePathUri Fully qualified source path URI of the feed's XML file.

The following file hosting solutions are supported:

  • s3
  • ftp and sftp
  • http and https

This must be accessible through the same file hosting solution as the metadata feed but can be empty before the data is ready.
CountryCode 0 or 1 string The ISO 3166-1 alpha-2 country code that this feed covers. Required if FeedType is not election-dates or voter-information.
FeedInactiveDate 0 or 1 date A date in ISO-8601 format that indicates when the feed will no longer be updated and should no longer be ingested.
  • For evergreen feeds, this should most likely not be set at all unless the feed is being deprecated.
  • For limited feeds, this should be set to two weeks after the end date of the last ElectionEvent in the feed or two weeks after the last post-election update is expected. Note that if an ElectionEvent is canceled with no expected updates, then the FeedInactiveDate can precede the EndDate for the ElectionEvent.
  • For yearly feeds, like with limited feeds, this should be set to at least two weeks after the end date of the last ElectionEvent, but it should also be no earlier than two weeks after the end of the year the feed is for. For example, for a 2024 feed, the FeedInactiveDate should be set to 2025-01-14 in the common case where all elections have ended on or before 2024-12-31. It may be set even later if elections are postponed, if runoffs occur in 2025, or if election events otherwise continue into 2025.
ElectionEventCollection 0 or 1 ElectionEvent Contains information about elections covered by this feed. This is only respected for the feed types PRE_ELECTION or ELECTION_RESULTS.
OfficeholderSubFeed 0 or 1 OfficeholderSubFeed Contains information about the officeholders covered by this feed. This is only respected for the feed type OFFICEHOLDER.