Navigating through CountryRisk.io’s API
Nothing beats Excel for hacking some data together, testing some ideas or producing some quick charts for a presentation.
Mar 12, 2020
UPDATE: Please always check the API documentation page for the current API endpoints and base url.
You find the docu here: https://apidocs.countryrisk.io
Nothing beats Excel for hacking some data together, testing some ideas or producing some quick charts for a presentation. BUT — and this is a big but — if you want to automatize workflows and streamline processes, spreadsheets typically don’t cut it. Effectively, information and knowledge are locked away in the spreadsheet and are difficult to use across an organization because of different access rights or lack of standardization.
APIs — Application Programming Interfaces — address many of these issues and allow better performance, quality and innovation. In the past, we provided our CountryRisk.io Risk Scores to our clients via spreadsheets. But we’ve moved with the times. We are happy to announce yet another platform update that makes our data available through APIs.
In this blog post, we want to demo how you can use the API. Like always, get in touch with us if you want to learn more or have some specific use-cases in mind.
Getting started: Your API credentials and our API docs
To gain access to the CountryRisk.io API, you’ll need some credentials that consist of a username and token (aka API key). Drop us an email ([email protected]) to get your 30-day trial pass without any obligation and costs.
The documentation for our REST-API can be found here. There you’ll also find which so-called API endpoints are available and how to put together the various calls. For this blog post, we used Python — our preferred programming language within CountryRisk.io — but you can use any other framework and even Excel. (Sidenote: if you want to supercharge your spreadsheets, consider using xlwings).
What’s on the menu
In order to learn what different risk models CountryRisk.io offers, you can call the API to get some details.
Currently, there are three risk models:
- CountryRisk.io Sovereign Risk Score for sovereign credit risk
- CountryRisk.io ESG Risk Score for sovereign credit risk. This explicitly takes into account environmental and social factors.
- CountryRisk.io AML Risk Score, which measures a country’s vulnerability to money laundering and terrorist financing activities.
And on top of these, we feature the SDG Index, which is straight out of the UN SDSN. The SDG Index measures a country’s progress towards reaching the UN SDGs by 2030, and we think this is the best way to track a country’s development.
Now to retrieve data, we need to know the model code such as “sovereign” or “aml” and the ISO country code (e.g. ABW for Aruba or ZWE for Zimbabwe). To the country experts, you might know them by heart. For the novice or uninitiated, you simply make an API call to get a list of all available countries and related ISO codes.
Make your first API call
Now we’re ready to make our first API call to get some risk score data. If we’re interested in the five countries with the lowest and highest sovereign credit risk, for example, we specify in the API call the model name (i.e. “sovereign”), and the API will magically return a structured file with all the details, like so:
So, Switzerland ranks top with the lowest sovereign credit risk, followed by Australia, Luxembourg, Sweden and Germany. On the other end of the spectrum, we get Sudan, Venezuela, Burundi, Sierra Leone and Somalia. The tables above only show a very small set of details that is provided. But we actually present you with much more, such as the data quality, model structure and as we will see later, underlying indicator data.
The tables above show the values of the current year. But if we want to get a sense how the sovereign risk of Switzerland has changed over time, we can get the full history with a simple API call. If you look closely, the used endpoint changed for the next call. In our initial step above, we only specified the model of interest. Now, we specify in addition the country of interest (i.e. CHE for Switzerland).
As we can see, Switzerland’s risk has been low throughout the decades. There was a modest blip during the great financial crisis of 2008, but Switzerland’s strength was gradually restored in the following years.
The shaded area shows the forecast period until 2025. CountryRisk.io uses the IMF World Economic Outlook database for indicators such as GDP per capita, current account balance, etc. for its prognosis. While the risk score ranges from 0 to 100 — where higher values indicate higher risk — the same API call also returns information about the corresponding letter ratings. In Switzerland’s case, it’s sovereign credit rating is currently assessed AAA.
At CountryRisk.io, we want to be as transparent as possible and useful for our community. Hence, the API gives you access to the last piece of data and methodology for the model results. For instance, you can explore the risk profile of the country along different risk sections. This deep dive into the risk details shows that Switzerland is quite strong across all seven risk areas, but its exceptional strengths are in the areas of institutional quality — surprise, surprise — and solvency and liquidity. The only area that’s somewhat “edgy” is the private/financial sector strength where high debt levels weigh on the result. Overall, not much to worry about.
As part of the API response, you’ll also receive all the underlying indicators that are assessed in the risk score calculation. This includes some meta information, like description and source as well as historical values.
So for instance, in order to come up with the sovereign risk score, we assess 48 individual indicators, aggregate them into the above-mentioned risk sections (e.g. economic growth prospects), then ultimately into a final risk score.
Like the data for GDP per capita (in USD), the time series for Switzerland is plotted below.
A bit on ESG sovereign risk score
Our ESG Sovereign Risk Score gives you access to more than 100 indicators covering standard macroeconomic and financial indicators, plus environmental data for tracking CO2 emissions, climate change vulnerability or social data for quality of education, inclusion or health care among many others. Take a look!
Country risk profile
So far, we’ve only looked at a specific risk score. Getting the results for the other two risk scores and UN SDG Index are also a piece of cake. In Switzerland’s case, it shouldn’t come as a surprise that it performs well across all indices: credit risk and AML risk and in reaching the UN Sustainable Development Goals by 2030.
A use case: Portfolio view
Let’s say that your sovereign bond portfolio is invested in Switzerland (50% weight), Poland (25%) and Russia (25%). The first chart shows the time series of the sovereign risk score for the three countries, while just below you’ll see how a weighted version would look like.
Summary and way forward
The CountryRisk.io API complements our offering and makes it easier for you to integrate our data into your analysis, dashboards, risk management processes and a host of other use-cases.
We’re still just getting started and we will continue to add new features and data to our API. In the meantime, we’re here to support you as you work with our APIs. Please reach out to us if you are interested in a free trial period or presentation at your office, or should you wish to find out more of what you can build with the CountryRisk.io API.
Thanks to Jenny Asuncion.