{smcl} {* *! version 1.1.2 30oct2018}{...} {viewerjumpto "Syntax" "dbnomics##syntax"}{...} {viewerjumpto "Description" "dbnomics##description"}{...} {viewerjumpto "Options" "dbnomics##options"}{...} {viewerjumpto "Remarks" "dbnomics##remarks"}{...} {viewerjumpto "Examples" "dbnomics##examples"}{...} {viewerjumpto "Stored results" "dbnomics##stored"}{...} {viewerjumpto "Author" "dbnomics##author"}{...} {title:Title} {phang} {bf:dbnomics} {hline 2} Stata client for DB.nomics, the world's economic database ({browse "https://db.nomics.world":https://db.nomics.world}) {marker description}{...} {title:Description} {pstd} {cmd:dbnomics} provides a suite of tools to search, browse and import time series data from DB.nomics, the world's economic database ({browse "https://db.nomics.world":https://db.nomics.world}). DB.nomics is a web-based platform that aggregates and maintains time series data from various statistical agencies across the world. {cmd:dbnomics} only works with Stata 14.0 or higher. {pstd} {cmd:dbnomics} provides an interface between Stata and DB.nomics' API ({browse "https://api.db.nomics.world/apidocs":https://api.db.nomics.world/apidocs}). It enables creating custom queries through Stata's {help options:options} syntax (see {help dbnomics##examples:Examples}). To achieve this, the command relies on Erik Lindsley's libjson Mata library ({stata ssc install libjson:ssc install libjson}). {marker syntax}{...} {title:Syntax} {p 8 8 2} {it: Load list of providers} {p_end} {p 8 8 2} {cmdab:dbnomics} {cmdab:provider:s} [{cmd:,} {opt clear insecure}] {p_end} {p 8 8 2} {it: Load content tree for a given provider} {p_end} {p 8 8 2} {cmdab:dbnomics} {cmdab:tree} {cmd:,} {opt pr:ovider(PRcode)} [{opt clear insecure}] {p_end} {p 8 8 2} {it: Load dataset structure given a provider and dataset} {p_end} {p 8 8 2} {cmdab:dbnomics} {cmdab:data:structure} {cmd:,} {opt pr:ovider(PRcode)} {opt d:ataset(DScode)} [{opt clear} {opt insecure}] {p_end} {p 8 8 2} {it: Load list of series for a given provider and dataset} {p_end} {p 8 8 2} {cmdab:dbnomics} {cmdab:series} {cmd:,} {opt pr:ovider(PRcode)} {opt d:ataset(DScode)} [{it:dimensions_opt}|{opt sdmx(SDMX_mask)}] [{opt clear} {opt insecure} {opt limit(int)} {opt offset(int)}] {p_end} {p 8 8 2} {it: Import series for a given provider and dataset} {p_end} {p 8 8 2} {cmdab:dbnomics} {cmdab:import} {cmd:,} {opt pr:ovider(PRcode)} {opt d:ataset(DScode)} [{it:dimensions_opt}|{opt sdmx(SDMX_mask)}|{opt series:ids(SERIES_list)}] [{opt clear} {opt insecure} {opt limit(int)} {opt offset(int)}] {p_end} {p 8 8 2} {it: Load a single series} {p_end} {p 8 8 2} {cmdab:dbnomics} {cmdab:use} {it:series_id} {cmd:,} {opt pr:ovider(PRcode)} {opt d:ataset(DScode)} [{opt clear} {opt insecure}] {p_end} {p 8 8 2} {it: Search for data across DB.nomics' providers} {p_end} {p 8 8 2} {cmdab:dbnomics} {cmdab:find} {it:search_str} [{cmd:,} {opt clear} {opt insecure} {opt limit(int)} {opt offset(int)}] {p_end} {p 8 8 2} {it: Load and display recently updated datasets} {p_end} {p 8 8 2} {cmdab:dbnomics} {cmdab:news} [{cmd:,} {opt clear} {opt insecure} {opt limit(int)} {opt offset(int)}] {p_end} {synoptset 25 tabbed}{...} {synopthdr} {synoptline} {syntab:Main} {synopt:{bf:provider(}{it:PRcode}{bf:)}}declare the reference data provider ({it:e.g.} AMECO, IMF, Eurostat) {p_end} {synopt:{bf:dataset(}{it:DScode}{bf:)}}declare the reference dataset ({it:e.g.} PIGOT, BOP, ei_bsin_m) {p_end} {synopt:{bf:clear}}replace data in memory {p_end} {synopt:{bf:insecure}}connect via {it:http} instead of the default https.{p_end} {syntab:For {cmd:series} and {cmd:import} only} {synopt:{it:dimensions_opt}}provider- and dataset-specific options to filter series (see {help dbnomics##examples:Examples}){p_end} {synopt:{bf:sdmx(}{it:SDMX_mask}{bf:)}}input an SDMX mask to select specific series ({bf:Note:} not all providers support this option){p_end} {synopt:{bf:limit(}{it:int}{bf:)}}limit the number of series to load{p_end} {synopt:{bf:offset(}{it:int}{bf:)}}skip the first {it:int} result(s){p_end} {syntab:For {cmd:import} only} {synopt:{bf:seriesids(}{it:SERIES_list}{bf:)}}input a comma-separated list to load specific time series{p_end} {syntab:For {cmd:use} only} {synopt:{it:series_id}}identifier of the series (see {help dbnomics##examples:Examples}){p_end} {syntab:For {cmd:find} and {cmd:news} only} {synopt:{bf:limit(}{it:int}{bf:)}}limit the number of results to display{p_end} {synopt:{bf:offset(}{it:int}{bf:)}}skip the first {it:int} result(s){p_end} {synoptline} {p2colreset}{...} {marker options}{...} {title:Options} {dlgtab:Main} {phang} {opt provider(PRcode)} sets the source with the data of interest. The list of data providers is regularly updated by the DB.nomics team. To get the list of available data providers, type {cmdab:dbnomics} {cmdab:provider:s} [{cmd:,} {opt clear}].{p_end} {phang} {opt dataset(DScode)} sets the dataset with the time series of interest. To get a hierarchy of all datasets linked to a particular {opt provider(PRcode)}, type {cmdab:dbnomics} {cmdab:tree}{cmd:,} {cmdab:pr:ovider(}{it:PRcode}{cmd:)} [{opt clear}]. ({bf:Note:} some datasets in the category tree may not be accessible). {p_end} {phang} {opt clear} clears data in memory before loading data from DB.nomics. {p_end} {phang} {opt insecure} instructs dbnomics to access the DB.nomics platform via the {it:http} protocol, instead of the more secure {it:https}. {p_end} {bf:{dlgtab:series}} {marker dimensions_opt}{...} {phang} {opt dimensions_opt(dim_values)} are options that depend on the specific {opt provider(PRcode)} and {opt dataset(DScode)} and are used to identify a subset of series. A list of dimensions can be obtained using {cmd: dbnomics datastructure,} {opt provider(PRcode)} {opt dataset(DScode)}. For example, if the dimensions of {opt dataset(DScode)} are {cmd:freq.unit.geo}, accepted options for{cmd: dbnomics series,}{opt (...)} and {cmd: dbnomics import,}{opt (...)} are {opt freq(codelist)}, {opt unit(codelist)} and {opt geo(codelist)}. Each {opt dimension_opt(dim_values)} can contain one or more values in a space or comma-separated list, so as to select multiple dimensions at once ({it:e.g.}, a list of countries). {it:Note:} {cmd:dbnomics} is not able to validate user-inputted {opt dimension_opt(dim_values)}; if {opt dimension_opt(dim_values)} is incorrectly specified, {cmd:dbnomics} may throw an error or return the message {err: no series found}. See {help dbnomics##examples:Examples}. {p_end} {marker sdmx}{...} {phang} {opt sdmx(SDMX_mask)} accepts an "SDMX mask" containing a list of dimensions separated with a dot "." character. The dimensions are specific to each {opt provider(PRcode)} and {opt dataset(DScode)} and must be provided in the order specified by the {opt dataset(DScode)} data structure. The data structure can be obtained using {cmd: dbnomics datastructure,} {opt provider(PRcode)} {opt dataset(DScode)}. {it:Note:} some providers do not support this feature. In such case {cmd: dbnomics} may throw an error or return the message {err:no series found}. {p_end} {p 8 8 2}{it:Note}: {opt dimensions_opt(dim_values)} and {opt sdmx(SDMX_mask)} are mutually exclusive. {p_end} {phang} {opt limit(int)} sets a limit to the number of series to load via dbnomics. A {err:Warning} message is issued if the total number of series identified is larger than the inputted {opt limit(int)}. {p_end} {phang} {opt offset(int)} skips the first {it:int} series when loading data from dbnomics. This option can be combined with {opt limit(int)} to get a specific subset of series. {p_end} {bf:{dlgtab:import}} {phang} {opt dimensions_opt(dim_values)} {help dbnomics##dimensions_opt:see above}.{p_end} {phang} {opt sdmx(SDMX_mask)} {help dbnomics##sdmx:see above}.{p_end} {phang} {opt seriesids(SERIES_list)} accepts a comma-separated list of series identifiers that belong to a {opt provider(PRcode)} and {opt dataset(DScode)}. {p_end} {p 8 8 2}{it:Note}: {opt dimensions_opt(dim_values)}, {opt sdmx(SDMX_mask)} and {opt seriesids(SERIES_list)} are mutually exclusive. {p_end} {phang} {opt limit(int)} sets a limit to the number of series to load via dbnomics. A {err:Warning} message is issued if the total number of series identified is larger than the inputted {opt limit(int)}. {p_end} {phang} {opt offset(int)} skips the first {it:int} series when loading data from dbnomics. This option can be combined with {opt limit(int)} to get a specific subset of series. See {help dbnomics##examples:Examples}. {p_end} {bf:{dlgtab:use}} {phang}{it:series_id} is the unique identifier of a time series belonging to {opt provider(PRcode)} and {opt dataset(DScode)}.{p_end} {bf:{dlgtab:find/news}} {phang}{opt limit(int)} sets the maximum number of results to load and display. {p_end} {phang} {opt offset(int)} skips the first {it:int} results. May be combined with {opt limit(int)} to get a specific subset of results. {p_end} {phang} {marker remarks}{...} {title:Remarks} {*:{pstd} The DB.nomics data model is characterised by the following hiearchy: {it: provider -> datasets -> time series -> observations}.{p_end}} {pstd} {cmd:dbnomics} has two main dependencies: {p_end} {pstd} 1) The Mata json library {cmd:libjson} by Erik Lindsley, needed to parse JSON strings. It can be found on SSC: {stata ssc install libjson}. {p_end} {pstd} 2) The routine {cmd:moss} by Robert Picard & Nicholas J. Cox, needed to clean some unicode sequences. It can be found on SSC: {stata ssc install moss}. {p_end} {pstd} After each API call, {cmd:dbnomics} stores significant metadata in the form of {help char:dataset characteristics}. Type {cmd:{stata "char li _dta[]":char li _dta[]}} after {cmd:dbnomics} to obtain important info about the data, {it:e.g.}, the API endpoint. {p_end} {marker examples}{...} {title:Examples} {pstd}{it:Search for producer price data on the DB.nomics platform:}{p_end} {space 8}{cmd:. dbnomics find "producer price", clear}{space 4}{cmd:///}{space 2}{txt:({stata `"dbnomics find "producer price", clear "':click to run})} {space 8}{it:(output omitted)} {pstd}{it:Load the list of available providers with additional metadata:}{p_end} {space 8}{cmd:. dbnomics }{cmdab:provider:s}{cmd:, clear}{space 4}{cmd:///}{space 2}{txt:({stata "dbnomics providers, clear":click to run})} {pstd}{it:Show recently updated datasets:}{p_end} {space 8}{cmd:. dbnomics news, clear}{space 4}{cmd:///}{space 2}{txt:({stata "dbnomics news, clear ":click to run})} {space 8}{it:(output omitted)} {pstd}{it:Load the dataset tree of of the {bf:AMECO} provider:}{p_end} {space 8}{cmd:. dbnomics tree, }{cmdab:pr:ovider}{cmd:(AMECO) clear}{space 4}{cmd:///}{space 2}{txt:({stata "dbnomics tree, provider(AMECO) clear":click to run})} {pstd}{it:Analyse the structure of dataset {bf:PIGOT} for provider {bf:AMECO}:}{p_end} {space 8}{cmd:. dbnomics }{cmdab:data:structure}{cmd:, }{cmdab:pr:ovider}{cmd:(AMECO) {cmdab:d:ataset}{cmd:(PIGOT)} clear}{space 4}{cmd:///}{space 2}{txt:({stata "dbnomics datastructure, provider(AMECO) dataset(PIGOT) clear":click to run})} {space 8}{cmd:Price deflator gross fixed capital formation: other investment} {space 8}82 series found. Order of dimensions: (freq.unit.geo) {pstd}{it:List all series in {bf:AMECO/}{bf:PIGOT} containing deflators in national currency:}{p_end} {space 8}{cmd:. dbnomics }{cmdab:series}{cmd:, }{cmdab:pr:ovider}{cmd:(AMECO) {cmdab:d:ataset}{cmd:(PIGOT)} {cmd:unit(national-currency-2015-100)} clear} {space 8}{txt:({stata "dbnomics series, provider(AMECO) dataset(PIGOT) unit(national-currency-2015-100) clear":click to run})} {space 8}39 of 82 series selected. Order of dimensions: (freq.unit.geo) {pstd}{it:Import all series in {bf:AMECO/}{bf:PIGOT} containing deflators in national currency:}{p_end} {space 8}{cmd:. dbnomics }{cmdab:import}{cmd:, }{cmdab:pr:ovider}{cmd:(AMECO) {cmdab:d:ataset}{cmd:(PIGOT)} {cmd:unit(national-currency-2015-100)} clear} {space 8}{txt:({stata "dbnomics import, provider(AMECO) dataset(PIGOT) unit(national-currency-2015-100) clear":click to run})} {space 8}Processing 39 series {space 8}........................................ {space 8}{bf:39 series found and imported} {pstd}{it:Import a few {bf:AMECO/}{bf:PIGOT} series:}{p_end} {space 8}{cmd:. dbnomics import, pr(AMECO) d(PIGOT) }{cmdab:series:ids}{cmd:(ESP.3.1.0.0.PIGOT,SVN.3.1.0.0.PIGOT,LVA.3.1.99.0.PIGOT) clear} {space 8}{txt:({stata "dbnomics import, pr(AMECO) d(PIGOT) seriesids(ESP.3.1.0.0.PIGOT,SVN.3.1.0.0.PIGOT,LVA.3.1.99.0.PIGOT) clear":click to run})} {space 8}Processing 3 series {space 8}... {space 8}{bf:3 series found and imported} {pstd}{it:Import one specific series from {bf:AMECO/}{bf:PIGOT}:}{p_end} {space 8}{cmd:. dbnomics use ESP.3.1.0.0.PIGOT, pr(AMECO) d(PIGOT)}{cmd: clear} {space 8}{txt:({stata "dbnomics use ESP.3.1.0.0.PIGOT, pr(AMECO) d(PIGOT) clear":click to run})} {space 8}Annually – (National currency: 2015 = 100) – Spain (AMECO/PIGOT/ESP.3.1.0.0.PIGOT) {space 8}(62 observations read) {pstd}{it:{bf:Eurostat} supports SMDX queries}. {it:Import all series in {bf:Eurostat/}{bf:ei_bsin_q_r2} related to Belgium:}{p_end} {space 8}{cmd:. dbnomics }{cmdab:import}{cmd:, }{cmdab:pr:ovider}{cmd:(Eurostat) {cmdab:d:ataset}{cmd:(ei_bsin_q_r2)} {cmd:geo(BE) s_adj(NSA)} clear} {space 8}{txt:({stata "dbnomics import, provider(Eurostat) dataset(ei_bsin_q_r2) geo(BE) s_adj(NSA) clear":click to run})} {space 8}Processing 14 series {space 8}.............. {space 8}{bf:14 series found and imported} {pstd}{it:Do the same using {cmd:sdmx}:}{p_end} {space 8}{cmd:. dbnomics }{cmdab:import}{cmd:, }{cmdab:pr:ovider}{cmd:(Eurostat) {cmdab:d:ataset}{cmd:(ei_bsin_q_r2)} {cmd:sdmx(Q..NSA.BE)} clear} {space 8}{txt:({stata "dbnomics import, provider(Eurostat) dataset(ei_bsin_q_r2) sdmx(Q..NSA.BE) clear":click to run})} {space 8}Processing 14 series {space 8}.............. {space 8}{bf:14 series found and imported} {pstd}{it:The {bf:Eurostat/}{bf:urb_ctran} dataset offers 12280 series, more than permitted at once by DB.nomics}:{p_end} {space 8}{cmd:. dbnomics }{cmdab:series}{cmd:, }{cmdab:pr:ovider}{cmd:(Eurostat) {cmdab:d:ataset}{cmd:(urb_ctran)} clear} {space 8}{txt:({stata "dbnomics series, pr(Eurostat) d(urb_ctran) clear":click to run})} {space 8}{err:Warning: series set larger than dbnomics maximum provided items.} {space 8}{err:Use the {cmd:offset} option to load series beyond the 1000th one.} {space 8}{txt:12280 series selected. Order of dimensions: (FREQ.indic_ur.cities). {bf:Only #1 to #1000 retrieved}} {pstd}{it:Using {cmd:limit} and {cmd:offset}, we can instruct {cmd:dbnomics} to only get series #1001 to #1100}:{p_end} {space 8}{cmd:. dbnomics }{cmdab:import}{cmd:, }{cmdab:pr:ovider}{cmd:(Eurostat) {cmdab:d:ataset}{cmd:(urb_ctran)} {cmd:limit(100)} {cmd:offset(1000)} clear} {space 8}{txt:({stata "dbnomics import, pr(Eurostat) d(urb_ctran) limit(100) offset(1000) clear":click to run})} {space 8}Processing 100 series {space 8}.................................................. 50 {space 8}.................................................. 100 {space 8}{bf:12280 series found and #1001 to #1100 loaded} {marker results}{...} {title:Stored results} {pstd} {cmd:dbnomics} stores the following in {cmd:r()}: {synoptset 15 tabbed}{...} {p2col 5 15 19 2: Local}{p_end} {synopt:{cmd:endpoint}}name of {cmd:dbnomics} subcommand{p_end} {synopt:{cmd:cmd#}}command to load # result shown (For {cmd:find} and {cmd:news} only){p_end} {p2colreset}{...} {marker author}{...} {title:Author} {pstd} Simone Signore{break} signoresimone at yahoo [dot] it {p_end} https://dbnomics-stata.github.io/dbnomics/