API reference: series

Endpoint: /series

The /series endpoint allows obtaining data and metadata of one or more series, filtering by the time index, changing temporal aggregation and changing units, between other operations.

• Parameters
  • ids
  • representation_mode
  • collapse
  • collapse_aggregation
  • limit
  • start
  • start_date
  • end_date
  • format
  • header
  • sort
  • metadata
  • decimal
  • sep
  • flatten

Parameters

ids

Comma separated list of series ids. Data results will have a column for each series id, in the same order.

This parameter is mandatory for making a call. In case is omitted, result will be an error.

Each identifier of a series can have a suffix for:

• Changing representation mode (representation_mode).
• Changing temporal aggregation (collapse_aggregation).

When these attributes are used inside ids parameter, they must be separated using ":" character. The order of the components does not affect the order of the operation.

Examples:

ids=2.4_DGI_1993_T_19,134.2_B_0_0_6:change
ids=2.4_DGI_1993_T_19,134.2_B_0_0_6:sum:change
ids=2.4_DGI_1993_T_19,134.2_B_0_0_6:change:sum
ids=2.4_DGI_1993_T_19:percent_change,134.2_B_0_0_6:sum:change
ids=2.4_DGI_1993_T_19:end_of_period:percent_change,134.2_B_0_0_6:sum:change

representation_mode

Indicates the representation mode of the series. It is applied to all in the ids parameter not having a different representation mode applied.

Representation mode by default is the original value of the series (value).

Available representation modes are:

• value: Default representation mode. Returns the original value of the serie.
• change: Returns the absolute difference between value of t period and t-1 period.
• percent_change: Returns percentage variation of the value in the t period and t-1 period.
• percent_change_a_year_ago: Returns percentage variation between t period value and the same t period, a year ago.

Available transformation functions in representation_mode can also be specified for individual series using :percent_change notation, together with series id:

representation_mode parameter will continue to affect all series where no individual representation mode has been specified.

collapse

collapse parameter modifies sample frequency of series of the query. It must be used in combination with collapse_aggregation to specify a temporal aggregation function, when necessary.

Available options are:

• year: Show data yearly aggregated.
• quarter: Show data quarterly aggregated.
• month: Show data monthly aggregated.
• week: Show data weekly aggregated.
• day: Show data daily aggregated.

If not specified, data of a single series query is return using original frequency of the serie.

If multiples series of different frequencies are being called at the same time, the lowest frequency of all of them will be used (ie.: if you ask for daily, monthly and quarterly series in the same call, they will all be converted to quarterly frequency).

If you ask for a higher frequency level in collapse than the lowest one available between asked series, the query will return an error.

collapse parameter affects globally to all series selected from the ids parameter in the API call.

collapse_aggregation

collapse_aggregation parameter indicates the temporal aggregation function that must be used to make all the series in the call have the same frequency (ie.: what operation should be used to convert a monthly series in a yearly series).

This aggregation function will act over data of:

• Series with higher original aggregation level (highest frequency) than the one specified in collapse parameter.
• In case collapse parameter is not specified, series of higher aggregation level than the one of the series with the lowest temporal aggregation level of all.

Available options are:

• avg: Calculates the average of all values. This is the default option if no collapse_aggregation parameter is specified.
• sum: Sum all values.
• end_of_period: Last value of the aggregated period.
• min: Minimum value of the aggregated period.
• max: Maximum value of the aggregated period.

Temporal aggregation functions available in collapse_aggregation parameter can also be specified for individual series using :sum notation together with series id:

collapse_aggregation parameter will continue to affect all series that have no temporal aggregation function individually specified.

limit

Parameter used together with start to control pagination of API call results. Must be a positive integer not greater than 1000. Default value is 100.

start

Parameter used together with limit to control pagination of API call results. Must be a positive integer or 0. Default value is 0.

start parameter indicates the "number of periods after start_date" (or the "number of periods before end_date", depending on asc or desc sorting criteria specified on sort parameter) that should be skipped from beginning or end of the series before staring to return values.

start_date

start_date parameter indicates the less recent date where API results should start, when data is available. Values where time index is equal to start_date value will be included. It is a temporal filter over time index of all series in the API call.

end_date

end_date parameter indicates the most recent date where API results should end, when data is available. Values where time index is equal to end_date will be included. It is a temporal filter over time index of all series in the API call.

format

Specifies the format of the results. JSON is the default.

Available options are:

• json: Returns a JSON object with data and metadata of the series.
• csv: Returns selected series in a comma separated format. It does not include metadata.

header

Specifies attributes of series to be used as headers of the CSV file columns. Uses titles as default, being the shortest human readable titles of the series.

Available options are:

• titles: Series titles as oferta_global_pib (default).
• ids: Series unique identifiers. The same values passed in ids parameter.
• descriptions: Complete descriptions of the series as Plazo fijo entre 60-89 días en millones de pesos. Categoría II-VI.

sort

Specifies the sorting direction in which values are returned. asc is the default value.

Available options are:

• asc: Less recent values first (default).
• desc: Most recent values first.

metadata

Specifies the level of metadata detail required by the user, being simple the default. Only applies when format=json.

Available options are:

• none: No metadata is returned, only data.
• only: No data is returned, only metadata.
• simple: Only important metadata to understand and use the series is returned (default).
• full: All metadata available is returned.

decimal

Specifies character used for decimal numbers. . is the default. Only applies when format=csv.

Available options are:

• ,: Comma.
• .: Dot.

sep

Specifies the character that separates values in a CSV file. , is the default. Only applies when format=csv.

Any UTF-8 character can be used, but it is highly recommended to keep the default (comma) in most cases.

flatten

Specifies if the metadata results should be returned with a flat hierarchy.

When parameter is not included, API call result has a nested structure:

    {
        "catalog": [<catalog_meta>],
        "dataset": [<dataset_meta>],
        "distribution": [<distribution_meta>],
        "field": [<field_meta>],
    }

When flatten is included, API call metadata result has a flat structure:

    {
        catalog_meta1: ...,
        catalog_meta2: ...,
        dataset_meta1: ...,
        <level>_<meta_key>: <meta_value>
        ...
    }