Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/nomadbyte/fredcpp

FRED API Client for C++
https://github.com/nomadbyte/fredcpp

Last synced: 12 days ago
JSON representation

FRED API Client for C++

Awesome Lists containing this project

README 

        

fredcpp: FRED API Client for C++ {#main}

================================



Overview

--------



`fredcpp` is a third-party C++ library to access [Federal Reserve Economic Data

(FRED®)][fred] database via the web-API as published and maintained by

[Federal Reserve Bank of St. Louis][stlouisfed].



[FRED®][fred] represents an extensive collection of economic data series,

compiled and regularly updated from a large number of data sources. It is one of

the world's most comprehensive online economic databases. Please visit the

official [St. Louis Fed FRED®][fred] site for more information about

FRED® and details on how to obtain FRED API access. There you can also find

excellent [FRED API documentation][fredapi] which references the supported

queries and parameters.



> __DISCLAIMER__: `fredcpp` (FRED API Client for C++) is not affiliated in any

> way with St. Louis Fed and as such is not officially maintained or otherwise

> supported by St. Louis Fed.



`fredcpp` is a free software; the use, copy, and distribution rights are granted

under the terms of the @ref fredcpplicense | [MIT License][fredcpplicense].



[stlouisfed]: http://www.stlouisfed.org "Federal Reserve Bank of St. Louis"

[fred]: http://www.research.stlouisfed.org/fred2/ "Federal Reserve Economic Data (FRED)"

[fredapi]: http://api.stlouisfed.org/docs/fred/ "FRED API documentation"



[fredcpp]: https://github.com/nomadbyte/fredcpp "fredcpp project space"

[fredcppusage]: doc/usage.md "fredcpp Usage"

[fredcpplicense]: LICENSE.md "MIT License"

[fredcppchangelog]: CHANGELOG.md "fredcpp ChangeLog"



[curlcabundle]: http://curl.haxx.se/docs/caextract.html "cURL CA Certificate bundle"



Features

--------



The main objective behind `fredcpp` is to shield C++ users from the details of

constructing and executing web-requests to FRED API, then parsing the results;

at the same time to provide an expressive way to specify FRED data-queries in

C++ context.



`fredcpp` main features:



- access to full set of available FRED entities (_series_, _release_,

  _category_, _source_) and related sub-queries

- uniform and expressive public C++ interface

- built-in HTTP request execution, XML response parsing, and central logging

  facilities

- limited external dependencies (effectively only for HTTP handling)

- __stand-alone ready__ with the supplied implementation for binding with

  cURL-library

- flexible integration with external HTTP stack, XML parser, and logging framework

  alternatives



Additionally, the following concerns are kept in focus:



- portability (relies mainly on STL support)

- ease of build configuration (CMake-based)

- ease of use (example programs supplied)

- extensibility (includes suites of unit and acceptance tests with Google's gtest)

- customization (source-code available to changes per virtues of free software)



Refer to @ref fredcppusage | [fredcpp Usage][fredcppusage] page for more details.



Updates and details about the current version listed in 

@ref fredcppchangelog | [fredcpp ChangeLog][fredcppchangelog].



At-a-glance

-----------



A shortcut to get started with `fredcpp`, assuming you are familiar with

`CMake`, have a C++ compiler, cURL (`libcurl`) library and headers installed.



> __HTTPS-NOTE__: Starting 08/18/2015, FRED API requires HTTPS access for added

> security. `fredcpp` has been updated to generate HTTPS requests. However, `fredcpp`

> users need to make sure that HTTP executor used with `fredcpp` has been

> properly configured to handle HTTPS requests. CA Certificate used by FRED API

> must be available for verification in the user's environment.

>

> To configure `CurlHttpClient` supplied with `fredcpp`, download the CA Certificate

> bundle `cacert.pem` from [cURL CA Extract page][curlcabundle] to the

> `fredcpp` root -- this is needed to run acceptance tests.

> For use once installed, set the evironment variable `CURL_CA_BUNDLE` to point to 

> the downloaded file. Alternatively, call `CurlHttpClient::withCACertFile(path)`

> method to configure this explicitly from the user code, by default the file is

> expected in the running process' work directory.



> __NOTE__: On Windows generate `CMake` files with `"NMake Makefiles"` for MSVC

> `NMAKE`.



From `fredcpp` source directory:



    echo "$FRED_API_KEY" > api.key



    mkdir build

    cd build

    cmake -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=RelWithDebInfo ..

    make clean all

    make test

    ctest -V



    cd examples

    ./example1

    cat example.txt



Successful?



    make install



Use `fredcpp` library in your projects:



    #include 



    #include 

    #include 

    #include 



    ......



      fredcpp::Api api;



      api.withLogger( fredcpp::external::SimpleLogger::getInstance() )

         .withExecutor( fredcpp::external::CurlHttpClient::getInstance() )

         .withParser( fredcpp::external::PugiXmlParser::getInstance() )

         ;



      // set your FRED API key



      std::string yourApiKey;



    .......



      api.withKey( yourApiKey );



      // request the recent 10 observations for series "CBIC1"



      fredcpp::Api response;



      api.get( ApiRequestBuilder::SeriesObservations("CBIC1")

                                  .withSort("desc")

                                  .withLimit("10")

              , response );



      if ( !response.good() ) {

        FREDCPP_LOG_ERROR( response.error );

        exit( response.error.status );



      } else {

        FRECPP_LOG_INFO( response );

      }



    ......



Compile and link against the installed `fredcpp` library (assuming installation

with default `/usr/local` prefix):



    g++ example.cpp -lfredcpp -lcurl



More docs:



    make doc



See more examples in `examples` source sub-directory. See the official [FRED API

documentation][fredapi] for details on available requests and parameters.



Building and installation

-------------------------



[CMake](http://www.cmake.org "CMake") is needed to build and install `fredcpp`

library. CMake supports a variety of platforms and C++ compilers and

automatically selects comprehensive compiling options; however, it also allows

manual configuration if needed. Please download and install an up-to-date CMake

release for your platform if required.



1. Unpack the `fredcpp` source-code into a directory and create a

   build directory inside it (for CMake out-of-source build):



       mkdir build



2. Change to the build directory and configure CMake build-parameters (use CMake

   GUI tools, e.g. `cmake-gui` OR specify these on CMake command-line):

   - __Generator type__ - by default CMake chooses platform-specific generators;

     for consistency we prefer makefiles:



         -G "Unix Makefiles"

          OR

         -G "NMake Makefiles"



   - __FRED API key file location__ (`FREDCPP_API_KEY_FILE`) - needed here for

     acceptance testing. By default key is expected in `api.key` file in the

    `fredcpp` source directory

   - __Build type__ (`CMAKE_BUILD_TYPE`) - `Debug` by CMake default, but for

     optimized performance should be set to `RelWithDebInfo` or `Release`

   - __Installation prefix__ (`CMAKE_INSTALL_PREFIX`) - path to directory under

     which to install the resulting `fredcpp` library and headers. CMake provides

     platform-specific defaults.



3. Generate build files - once the parameters are set from CMake GUI, do `Configure`

   then `Generate` to produce the make files/projects:



   Example Windows command line to both configure and generate makefiles (for

   `NMAKE`) at once:



       cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=RelWithDebInfo ..



4. Build all `fredcpp` artifacts - static library, test-runners, and example

   programs will be built in respective sub-directories under the build directory.



   With `"NMake Makefiles"` on Windows, `NMAKE` should be used for `make` command:



       make clean all



5. Run unit and acceptance tests - expect all tests passed:

   > __NOTE__: a valid FRED API key is needed for acceptance tests.



     make test



   To see a more detailed test report, especially when any of the tests has

   failed:



       ctest -V



6. Optionally, examine and run the supplied examples - source code and

   executable files are in `examples` sub-directory of source or `build` directory

   respectively.



7. Optionally, generate documentation files (needs

   [Doxygen](http://www.doxygen.org "Doxygen") installed) - the resulting files are

   in `doc` sub-directory under `build`:



       make doc



8. Install `fredcpp` library and headers:

   > __NOTE__: By default `CMake` uses platform-specific install locations

   > (e.g. `/usr/local` on Linux, `%ProgramFiles%` on Windows etc.).

   > Define `CMAKE_INSTALL_PREFIX` `CMake` variable to override the

   > default install location. E.g. to install under a directory defined by 

   > `$FREDCPP_HOME` environment variable:



     cmake -DCMAKE_INSTALL_PREFIX="$FREDCPP_HOME" ..

     make install



9. Compile and link your program with `fredcpp` referring to the installed include

   and library locations.



Support

-------



We have already been using `fredcpp` in several production applications and

consider it stable for _our_ needs; a couple of new features are planned

(additional HTTP stack bindings). However, with the public release made widely

available, it could generate more feedback - perhaps, feature requests or

improvements, and not too many bug-reports, _hopefully_.



A public issue tracker may be eventually set up to address possible user-feedback.

Meanwhile, please direct your feedback to [fredcpp GitHub project page][fredcpp].



Of course, _Fork us on GitHub!_ as it goes to welcome your contribution.