openapi: 3.1.0
info:
title: "Moody's Data Buffet API"
version: 1.0.0
description: >-
The Moody's Analytics Data Buffet API provides programmatic access to
international and subnational economic, demographic, and financial time
series data and forecasts. It enables retrieval of individual series or
baskets of data, supports frequency conversion, mathematical
transformations, date range filtering, and vintage/versioning selection.
Code samples are available in C#, Java, Python, and R.
contact:
name: "Moody's Analytics"
url: https://www.economy.com/products/tools/data-buffet
license:
name: "Moody's Analytics Terms of Use"
url: https://www.moodys.com/web/en/us/about/legal/terms-of-use.html
externalDocs:
description: "Moody's Data Buffet API Documentation"
url: https://api.economy.com/data/v1/swagger
servers:
- url: https://api.economy.com/data/v1
description: "Moody's Analytics Data Buffet production server"
tags:
- name: Baskets
description: Operations for creating and managing collections of series requests
- name: Health
description: Service health monitoring
- name: Orders
description: Operations for managing data generation orders from baskets
- name: Reference
description: Operations for retrieving frequency, vintage, and file type metadata
- name: Search
description: Operations for searching available datasets and series
- name: Series
description: Operations for retrieving individual and multi-series time series data
security:
- oauth2: []
paths:
/oauth2/token:
post:
operationId: getAccessToken
summary: Moody's Obtain an Access Token
description: >-
Authenticates using OAuth2 client credentials and returns a bearer
access token for subsequent API requests.
tags:
- Reference
security: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- grant_type
- client_id
- client_secret
properties:
grant_type:
type: string
enum:
- client_credentials
description: The OAuth2 grant type. Must be client_credentials.
client_id:
type: string
description: The API client ID issued by Moody's Analytics.
client_secret:
type: string
description: The API client secret issued by Moody's Analytics.
responses:
"200":
description: Successfully obtained access token
content:
application/json:
schema:
$ref: "#/components/schemas/AccessToken"
"400":
description: Invalid grant type or missing credentials
"401":
description: Invalid client credentials
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/series:
get:
operationId: getSeries
summary: Moody's Retrieve a Single Time Series
description: >-
Returns data for a single economic, demographic, or financial time
series identified by its mnemonic. Supports frequency conversion,
mathematical transformations, date range filtering, and vintage
selection.
tags:
- Series
parameters:
- $ref: "#/components/parameters/mnemonic"
- $ref: "#/components/parameters/freq"
- $ref: "#/components/parameters/trans"
- $ref: "#/components/parameters/startDate"
- $ref: "#/components/parameters/endDate"
- $ref: "#/components/parameters/vintage"
responses:
"200":
description: Successfully retrieved time series data
content:
application/json:
schema:
$ref: "#/components/schemas/SeriesResponse"
"400":
description: Invalid parameters
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
"401":
description: Unauthorized - invalid or expired token
"404":
description: Series mnemonic not found
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
"429":
description: Rate limit exceeded
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/multi-series:
post:
operationId: getMultiSeries
summary: Moody's Retrieve Multiple Time Series
description: >-
Returns data for up to 25 time series in a single request. Each
series can have individual frequency, transformation, date range,
and vintage parameters. Useful for efficiently fetching related
economic indicators together.
tags:
- Series
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/MultiSeriesRequest"
responses:
"200":
description: Successfully retrieved multiple time series
content:
application/json:
schema:
$ref: "#/components/schemas/MultiSeriesResponse"
"400":
description: Invalid request or exceeded 25 series limit
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
"401":
description: Unauthorized - invalid or expired token
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/baskets:
get:
operationId: listBaskets
summary: Moody's List All Baskets
description: >-
Returns a list of all data baskets owned by the authenticated user.
A basket is a saved collection of series requests that can be
executed as an order.
tags:
- Baskets
responses:
"200":
description: Successfully retrieved basket list
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Basket"
"401":
description: Unauthorized - invalid or expired token
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createBasket
summary: Moody's Create a New Basket
description: >-
Creates a new data basket with a collection of series requests.
Baskets can be saved and reused to generate orders for bulk data
retrieval.
tags:
- Baskets
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/BasketCreate"
responses:
"201":
description: Successfully created basket
content:
application/json:
schema:
$ref: "#/components/schemas/Basket"
"400":
description: Invalid basket definition
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
"401":
description: Unauthorized - invalid or expired token
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/baskets/{basketId}:
get:
operationId: getBasket
summary: Moody's Retrieve a Specific Basket
description: >-
Returns the details of a specific basket including its series
requests and configuration.
tags:
- Baskets
parameters:
- $ref: "#/components/parameters/basketId"
responses:
"200":
description: Successfully retrieved basket
content:
application/json:
schema:
$ref: "#/components/schemas/Basket"
"401":
description: Unauthorized - invalid or expired token
"404":
description: Basket not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: updateBasket
summary: Moody's Update an Existing Basket
description: >-
Updates the series requests and configuration of an existing basket.
tags:
- Baskets
parameters:
- $ref: "#/components/parameters/basketId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/BasketCreate"
responses:
"200":
description: Successfully updated basket
content:
application/json:
schema:
$ref: "#/components/schemas/Basket"
"400":
description: Invalid basket definition
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
"401":
description: Unauthorized - invalid or expired token
"404":
description: Basket not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteBasket
summary: Moody's Delete a Basket
description: >-
Permanently deletes a basket and its associated series requests.
tags:
- Baskets
parameters:
- $ref: "#/components/parameters/basketId"
responses:
"204":
description: Successfully deleted basket
"401":
description: Unauthorized - invalid or expired token
"404":
description: Basket not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orders:
get:
operationId: listOrders
summary: Moody's List All Orders
description: >-
Returns a list of all data generation orders for the authenticated
user. Orders are created from baskets and produce output files in
the requested format.
tags:
- Orders
responses:
"200":
description: Successfully retrieved order list
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Order"
"401":
description: Unauthorized - invalid or expired token
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createOrder
summary: Moody's Create a New Order
description: >-
Creates a new data generation order from a basket. The order will
be processed asynchronously and produce output in the specified
file format.
tags:
- Orders
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/OrderCreate"
responses:
"201":
description: Successfully created order
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"400":
description: Invalid order request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
"401":
description: Unauthorized - invalid or expired token
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orders/{orderId}:
get:
operationId: getOrder
summary: Moody's Retrieve a Specific Order
description: >-
Returns the status and details of a specific order, including
processing status and download URL when complete.
tags:
- Orders
parameters:
- $ref: "#/components/parameters/orderId"
responses:
"200":
description: Successfully retrieved order
content:
application/json:
schema:
$ref: "#/components/schemas/Order"
"401":
description: Unauthorized - invalid or expired token
"404":
description: Order not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orders/{orderId}/download:
get:
operationId: downloadOrder
summary: Moody's Download Order Output
description: >-
Downloads the output file for a completed order. The file format
is determined by the fileType specified when creating the order.
tags:
- Orders
parameters:
- $ref: "#/components/parameters/orderId"
responses:
"200":
description: Successfully downloaded order output
content:
application/octet-stream:
schema:
type: string
format: binary
"401":
description: Unauthorized - invalid or expired token
"404":
description: Order not found or not yet complete
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/search:
get:
operationId: searchSeries
summary: Moody's Search for Available Series
description: >-
Searches the Data Buffet repository for available series matching
the specified criteria. Supports filtering by keyword, geography,
source, and category.
tags:
- Search
parameters:
- name: query
in: query
description: >-
Search query string to match against series names, descriptions,
mnemonics, and metadata.
required: true
schema:
type: string
- name: geography
in: query
description: >-
Filter results by geographic area code (e.g., US for United
States, GB for United Kingdom, CN for China).
required: false
schema:
type: string
- name: source
in: query
description: >-
Filter results by data source identifier (e.g., BLS, BEA, IMF,
Eurostat).
required: false
schema:
type: string
- name: category
in: query
description: >-
Filter results by data category (e.g., GDP, Employment,
Inflation, Housing).
required: false
schema:
type: string
- name: offset
in: query
description: The number of results to skip for pagination.
required: false
schema:
type: integer
minimum: 0
default: 0
- name: limit
in: query
description: The maximum number of results to return per page.
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 25
responses:
"200":
description: Successfully retrieved search results
content:
application/json:
schema:
$ref: "#/components/schemas/SearchResults"
"400":
description: Invalid search parameters
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
"401":
description: Unauthorized - invalid or expired token
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/frequencies:
get:
operationId: listFrequencies
summary: Moody's List Available Data Frequencies
description: >-
Returns a list of all supported data frequencies (e.g., annual,
quarterly, monthly, weekly, daily) that can be used for frequency
conversion when retrieving series.
tags:
- Reference
responses:
"200":
description: Successfully retrieved frequency list
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/FrequencyInfo"
"401":
description: Unauthorized - invalid or expired token
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/vintages:
get:
operationId: listVintages
summary: Moody's List Available Vintages for a Series
description: >-
Returns a list of available data vintages (historical revisions)
for a specific series. Vintages enable access to previous versions
of data as originally published.
tags:
- Reference
parameters:
- $ref: "#/components/parameters/mnemonic"
responses:
"200":
description: Successfully retrieved vintage list
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/Vintage"
"400":
description: Invalid mnemonic
"401":
description: Unauthorized - invalid or expired token
"404":
description: Series mnemonic not found
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/filetypes:
get:
operationId: listFileTypes
summary: Moody's List Supported Output File Types
description: >-
Returns a list of supported output file types for order data
generation (e.g., CSV, Excel, XML, JSON).
tags:
- Reference
responses:
"200":
description: Successfully retrieved file type list
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/FileType"
"401":
description: Unauthorized - invalid or expired token
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/health:
get:
operationId: checkHealth
summary: Moody's Check Service Health
description: >-
Returns the current health status of the Data Buffet API service.
tags:
- Health
security: []
responses:
"200":
description: Service is healthy
content:
application/json:
schema:
$ref: "#/components/schemas/HealthStatus"
"503":
description: Service is unavailable
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
oauth2:
type: oauth2
description: >-
OAuth2 client credentials flow for authenticating API requests.
Obtain client_id and client_secret from your Moody's Analytics
account.
flows:
clientCredentials:
tokenUrl: https://api.economy.com/data/v1/oauth2/token
scopes: {}
parameters:
mnemonic:
name: mnemonic
in: query
description: >-
The unique series mnemonic identifier. Mnemonics follow the Data
Buffet naming convention, e.g., FGDP_US for US GDP or
EMPLPAY.IUSA for US total nonfarm payrolls.
required: true
schema:
type: string
examples:
usGdp:
summary: US Gross Domestic Product
value: FGDP_US
usPayrolls:
summary: US Total Nonfarm Payrolls
value: EMPLPAY.IUSA
freq:
name: freq
in: query
description: >-
The desired output frequency for the series. When specified,
frequency conversion is applied. For example, converting quarterly
GDP to annual.
required: false
schema:
type: string
enum:
- A
- Q
- M
- W
- D
trans:
name: trans
in: query
description: >-
The mathematical transformation to apply to the series values.
Supports common economic transformations.
required: false
schema:
type: string
enum:
- Level
- SimpleDifference
- PercentChange
- AnnualizedGrowth
- YearOverYearPercentChange
- CompoundAnnualGrowthRate
startDate:
name: startDate
in: query
description: >-
The start date for the data range in YYYY-MM-DD format. If omitted,
returns data from the beginning of the series.
required: false
schema:
type: string
format: date
endDate:
name: endDate
in: query
description: >-
The end date for the data range in YYYY-MM-DD format. If omitted,
returns data through the latest available observation or forecast.
required: false
schema:
type: string
format: date
vintage:
name: vintage
in: query
description: >-
The vintage date for accessing historical data revisions in
YYYY-MM-DD format. If omitted, returns the latest vintage.
required: false
schema:
type: string
format: date
basketId:
name: basketId
in: path
description: The unique identifier of the basket.
required: true
schema:
type: string
orderId:
name: orderId
in: path
description: The unique identifier of the order.
required: true
schema:
type: string
schemas:
AccessToken:
type: object
description: OAuth2 access token response.
required:
- access_token
- token_type
- expires_in
properties:
access_token:
type: string
description: The bearer access token for authenticating API requests.
example: example_value
token_type:
type: string
description: The type of token issued. Always "Bearer".
enum:
- Bearer
example: Bearer
expires_in:
type: integer
description: The number of seconds until the access token expires.
example: 10
SeriesResponse:
type: object
description: >-
Response containing a single time series with metadata and
observations.
required:
- mnemonic
- description
- frequency
- data
properties:
mnemonic:
type: string
description: The unique series mnemonic identifier.
example: example_value
description:
type: string
description: Human-readable description of the series.
example: A sample description.
frequency:
type: string
description: The frequency of the returned data.
enum:
- Annual
- Quarterly
- Monthly
- Weekly
- Daily
example: Annual
source:
type: string
description: The original data source (e.g., BLS, BEA, IMF).
example: example_value
geography:
type: string
description: The geographic area the series covers.
example: example_value
units:
type: string
description: >-
The unit of measurement for the series values (e.g., Billions
of Chained 2017 Dollars, Thousands of Persons, Index).
example: example_value
transformation:
type: string
description: The transformation applied to the data, if any.
example: example_value
startDate:
type: string
format: date
description: The start date of the returned data range.
example: '2026-01-15'
endDate:
type: string
format: date
description: The end date of the returned data range.
example: '2026-01-15'
vintage:
type: string
format: date
description: The vintage date of the returned data.
example: '2026-01-15'
lastUpdated:
type: string
format: date-time
description: When the series was last updated in the repository.
example: '2026-01-15T10:30:00Z'
isForecast:
type: boolean
description: >-
Whether the series contains forecast data from Moody's
Analytics models.
example: true
data:
type: array
description: >-
Array of date-value pairs representing the time series
observations and/or forecasts.
items:
$ref: "#/components/schemas/Observation"
example: []
Observation:
type: object
description: A single time series observation or forecast data point.
required:
- date
- value
properties:
date:
type: string
format: date
description: >-
The observation date in YYYY-MM-DD format. For frequencies
coarser than daily, represents the period start date.
example: '2026-01-15'
value:
type:
- number
- "null"
description: >-
The observation value. Null indicates missing or unavailable
data for this period.
example: example_value
status:
type: string
description: >-
Status indicator for the data point.
enum:
- History
- Forecast
- Preliminary
example: History
MultiSeriesRequest:
type: object
description: Request body for retrieving multiple series simultaneously.
required:
- series
properties:
series:
type: array
description: >-
Array of series requests. Maximum 25 series per request.
maxItems: 25
items:
$ref: "#/components/schemas/SeriesRequest"
example: []
SeriesRequest:
type: object
description: A single series request within a multi-series call.
required:
- mnemonic
properties:
mnemonic:
type: string
description: The unique series mnemonic identifier.
example: example_value
freq:
type: string
description: Desired output frequency.
enum:
- A
- Q
- M
- W
- D
example: A
trans:
type: string
description: Mathematical transformation to apply.
enum:
- Level
- SimpleDifference
- PercentChange
- AnnualizedGrowth
- YearOverYearPercentChange
- CompoundAnnualGrowthRate
example: Level
startDate:
type: string
format: date
description: Start date for the data range.
example: '2026-01-15'
endDate:
type: string
format: date
description: End date for the data range.
example: '2026-01-15'
vintage:
type: string
format: date
description: Vintage date for historical data revisions.
example: '2026-01-15'
MultiSeriesResponse:
type: object
description: Response containing multiple time series.
required:
- series
properties:
series:
type: array
description: Array of time series responses.
items:
$ref: "#/components/schemas/SeriesResponse"
example: []
Basket:
type: object
description: >-
A saved collection of series requests that can be executed as an
order for bulk data retrieval.
required:
- basketId
- name
- series
properties:
basketId:
type: string
description: Unique identifier for the basket.
example: '500123'
name:
type: string
description: User-defined name for the basket.
example: Example Title
description:
type: string
description: Optional description of the basket contents and purpose.
example: A sample description.
series:
type: array
description: The series requests contained in the basket.
items:
$ref: "#/components/schemas/SeriesRequest"
example: []
createdAt:
type: string
format: date-time
description: When the basket was created.
example: '2026-01-15T10:30:00Z'
updatedAt:
type: string
format: date-time
description: When the basket was last modified.
example: '2026-01-15T10:30:00Z'
BasketCreate:
type: object
description: Request body for creating or updating a basket.
required:
- name
- series
properties:
name:
type: string
description: User-defined name for the basket.
example: Example Title
description:
type: string
description: Optional description of the basket.
example: A sample description.
series:
type: array
description: The series requests to include in the basket.
items:
$ref: "#/components/schemas/SeriesRequest"
example: []
Order:
type: object
description: >-
A data generation order created from a basket. Orders are processed
asynchronously and produce downloadable output files.
required:
- orderId
- basketId
- status
properties:
orderId:
type: string
description: Unique identifier for the order.
example: '500123'
basketId:
type: string
description: The basket from which the order was generated.
example: '500123'
status:
type: string
description: Current processing status of the order.
enum:
- Pending
- Processing
- Complete
- Failed
example: Pending
fileType:
type: string
description: The output file format for the order.
example: example_value
createdAt:
type: string
format: date-time
description: When the order was created.
example: '2026-01-15T10:30:00Z'
completedAt:
type: string
format: date-time
description: When the order processing completed.
example: '2026-01-15T10:30:00Z'
downloadUrl:
type: string
format: uri
description: >-
URL to download the order output. Available only when status
is Complete.
example: https://www.example.com
errorMessage:
type: string
description: >-
Error description if the order failed. Present only when
status is Failed.
example: example_value
OrderCreate:
type: object
description: Request body for creating a new order.
required:
- basketId
- fileType
properties:
basketId:
type: string
description: The basket to generate the order from.
example: '500123'
fileType:
type: string
description: >-
The desired output file format. Use the /filetypes endpoint
to retrieve supported formats.
example: example_value
SearchResults:
type: object
description: Paginated search results for series queries.
required:
- totalCount
- results
properties:
totalCount:
type: integer
description: Total number of matching series across all pages.
example: 10
offset:
type: integer
description: The current pagination offset.
example: 10
limit:
type: integer
description: The maximum results per page.
example: 10
results:
type: array
description: Array of matching series metadata.
items:
$ref: "#/components/schemas/SeriesSummary"
example: []
SeriesSummary:
type: object
description: Summary metadata for a series returned in search results.
required:
- mnemonic
- description
properties:
mnemonic:
type: string
description: The unique series mnemonic identifier.
example: example_value
description:
type: string
description: Human-readable description of the series.
example: A sample description.
frequency:
typ
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/moodys-corporation/refs/heads/main/openapi/moodys-data-buffet-api-openapi.yml