Definitions

The Assembled Data Feeds API is built around a small set of core concepts that define how data is requested, processed, and delivered. This page provides clear definitions of those concepts so you can better understand how to configure and interact with feeds using the API.

Feed

A feed is the primary resource in the Assembled Data API. It represents a reusable configuration that defines what data should be extracted, how it should be processed, and when it should run.

A feed includes:

• A business identity (name and requesting carrier)
• A defined data scope (market selectors)
• Processing behavior (parameters)
• A schedule for execution

It is important to note that a feed defines a configuration, not the data output itself.

Feed ID and Feed Name

Each feed has two key identifiers:

The feedId is the authoritative identifier used in all API operations. It should be treated as an opaque value and stored for reuse. The feedName is intended for display and organization purposes and can be changed over time.

Feed Type

The feed type (feedType) defines how a feed behaves and what kind of data processing it performs.

Feeds of type AllAdds and ChangeSub are considered live or "regular" feeds, while Historical feeds follow a different processing model and use different supporting resources.

Regular and Historical Feeds

Assembled Data supports two distinct feed models:

Live (Regular) feeds (AllAdds, ChangeSub) are used for ongoing or recurring data extraction of live information. They rely on standard market selectors and support recurring schedules.

Historical feeds (Historical) are used to retrieve data over a defined date range. They use a separate selector model, are typically executed once, and include processing status and downloadable results. Additionally, access to these feeds is managed separately from access to regular feeds. Historical feeds are only available to consumers who have access to create historical feeds on the Architect UI. If you do not already have access or have a question regarding your access to historical feeds, please reach submit a support case on the ATPCO Support Portal.

Because of these differences, regular and historical feeds use different endpoints, validation rules, and authorization scopes.

Market Type

The market type (marketType) defines the business domain for the feed.

The selected market type affects how schedules are validated and which fare-selection rules apply to market selectors.

Market Selectors (Driver Files)

In the API implementation, a market selector defines a unit of market scope within a feed. The front-end Architect UI manages market selectors through a CSV upload called a driver file. Each selector specifies the criteria used to include data in processing, such as origin, destination, carrier, and trip type. The term "market selector" is used in the API definitions and endpoints to signify that the inclusion of markets in a feed need not strictly be done via a file, and market lists can be managed both via driver files and via a JSON payload.

Selectors also include flags that determine which types of fares are included (public, private, constructed, etc).

📝 Market selectors are managed separately from the feed definition and are always updated as a complete set.

As large market selector lists are a common need for Assembled Data consumers, the API uses gzip encoding to allow for large market selector lists to be retrieved or updated via the Assembled Data APIs. Use gzip encoding when retrieving or updating market selector JSON payloads that exceed 10 MB.

To leverage gzip encoding:

• Retrieval: Include header Accept-Encoding: gzip on retrieval
• Updates: Use content type application/gzip when the JSON payload for market selectors exceeds 10 MB. The request body should include the raw gzip-compressed bytes of the JSON document of market selectors.

Historical Market Selectors (Driver Files)

Historical feeds use a different selector model called historical market selectors.

In addition to standard selection criteria, these selectors include:

• A travel date range (startDate and endDate)
• Optional filters such as fare class or tariff
• Support for broader location definitions (airport or country codes)

These selectors are managed through dedicated historical endpoints.

Schedule

A schedule defines when a feed is eligible to run. It combines frequency, recurrence, date boundaries, and execution times.

All components of the schedule work together and must follow specific validation rules.

Schedule Frequency

The frequency determines how often a feed runs:

Historical feeds run Once.

Schedule Recurrence

The recurrence defines the specific day or group of days a feed runs (for example, Weekdays or Monday). This value is required for certain frequency types.

Schedule Times

Schedule times define the hours when a feed runs. Times are expressed in HH:00 format and are based on ET.

Allowed values depend on the selected market type and recurrence pattern, and the valid times correspond with existing ATPCO domestic and international subs times. See the Assembled Data user guide for more details.

Full-State Operations

The Assembled Data API uses full-state semantics for create and update operations.

This means:

• All required fields must be provided in the request
• Missing fields are treated as invalid
• Updates replace the entire resource rather than partially modifying it

This applies to feed creation, feed updates, and selector updates.

Feed Execution

While full details of how and when feeds execute can be found in the Assembled Data user guide, there are some details to note about how the API impacts how and when feeds execute.

Execution Eligibility

In order for a feed created by the API to be eligible to execute, the Assembled Data API requires two steps:

• Creating the feed schedule details (POST with the feed schedule information)
• Adding the market selectors (driver file) to the newly created feed (POST to the /{feedId}/market-selectors or /{feedId}/historical-market-selectors endpoint)

Feeds without market selectors will not execute at their scheduled times.

Historical Feed Execution

Historical feeds will execute as soon as market selectors are updated on the feed, to closely mirror the current behavior on the Architect UI.

Note that when updating market selectors on a historical feed, the feed will execute immediately, so take caution to update only when a historical feed ought to execute.

Problem Details (Error Responses)

The Assembled Data API uses a standardized error format based on RFC 7807 (“Problem Details”).

Error responses include fields such as:

• type (error category)
• title (short description)
• status (HTTP status code)
• detail (detailed explanation)
• instance (unique request identifier)
• timestamp (time of the error)

Some responses may also include a retryable indicator to help determine whether the request can be retried.

Authorization Scopes

Authorization scopes define what actions your application is allowed to perform.

The scopes included in your access token determine which endpoints and resources are available to your application. Please note that the scopes for historical feeds are only available to customers with current access to historical feeds.