Country Risk Public API

Our mission is to help you to make better country risk decisions. To achieve this, our CountryRisk.io API enables you to integrate CountryRisk.io data (e.g. risk scores) into your own applications and systems.

This is the documentation for version 1.0.0 of the API. Last update on Mar 18, 2020.

Base URL
https://countryrisk.io/api/v1

Getting started

Before using the API you need to get an API key by sending us an email (contact@countryrisk.io).

By using the CountryRisk.io API, you agree to the Countryrisk.io API Terms & Conditions ("Terms"). You find the Terms here. Please read these Terms carefully, as they are a legally binding agreement. We reserve the right to update and change the Terms.


Authentication

Send the Authorization header with all your requests. The value is apikey username:token.

curl \ -X GET 'https://countryrisk.io/api/v1/configuration/riskscoremodels/' \ -H 'Authorization: apikey username:token'

Errors

HTTP response codes indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error. In case of an error, the response body contains additional details. Examples of status codes with an error:

  • 403 — Unauthorized
  • 404 — Not Found
  • 405 — Method Not Allowed
  • 500 — Server Error

Configuration

Risk score models

Get risk score models.

Responses
  • 200 array[object]

    A list of risk score models.

    • title string

      Title

    • description string

      Description

    • source string

      Source

    • code string

      Code

      Values are aml, esg, sdg, and sovereign.

Definition
GET https://countryrisk.io/api/v1/configuration/riskscoremodels/
cURL example
curl \ -X GET https://countryrisk.io/api/v1/configuration/riskscoremodels/ \ -H "Content-Type: application/json"
Response example (200)
[ { "source": "CountryRisk.io Ltd", "code": "sovereign", "description": "Sovereign Risk Score", "title": "CountryRisk.io Sovereign Risk Score" }, { "source": "CountryRisk.io Ltd", "code": "esg", "description": "ESG Risk Score", "title": "CountryRisk.io ESG Risk Score" }, { "source": "CountryRisk.io Ltd", "code": "sdg", "description": "The SDG Index and Dashboards Report is the first worldwide study to assess where each country stands with regard to achieving the Sustainable Development Goals (SDGs) ...", "title": "CountryRisk.io SDG Index" }, { "source": "CountryRisk.io Ltd", "code": "aml", "description": "Anti-Money Laundering Country Risk Score", "title": "CountryRisk.io AML Risk Score" } ]

Countries

Get countries.

URL parameters
  • code string

    Country code

  • name string

    Country name

  • model string

    Ordering

    Values are code, -code, name, and -name.

Responses
  • 200 array[object]

    A list of countries.

    • name string

      Country name.

    • code string

      Country code.

Definition
GET https://countryrisk.io/api/v1/configuration/countries/
cURL example
curl \ -X GET https://countryrisk.io/api/v1/configuration/countries/ \ -H "Content-Type: application/json"
Response example (200)
[ { "name": "Australia", "code": "AUS" }, { "name": "Austria", "code": "AUT" }, { "name": "Sweden", "code": "SWE" } ]

Riskscores

Risk scores

Get risk scores by model.

URL parameters
  • model Required / string

    Risk score model

    Values are aml, esg, sdg, and sovereign.

  • country_code string

    Country code

  • country_name string

    Country name

  • ordering string

    Ordering

    Values are country_code, -country_code, country_name, and -country_name.

Responses
  • 200 object

    A list of risk scores.

    • model object

      Risk model definition.

      • model.type string

        Risk model type.

      • model.version string

        Risk model version number.

      • model.updateDate string(date)

        Date of update.

      • model.description string

        Risk model description.

      • model.source string

        Risk model source.

      • model.url string(uri)

        Risk model url for further information.

    • data array[object]
      • data.entity object

        Geographical information.

        • data.entity.geoType string

          Geographic type (e.g. country, region, municipality, ...).

        • data.entity.countryCode string

          Country code following the ISO 3166-1 alpha-3 codes.

        • data.entity.countryName string

          Country name.

        • data.entity.regionName string

          Region name (e.g. Asia, Latin America, ...).

        • data.entity.worldBankClassification string

          World Bank income classification (e.g. low-income economy, lower-middle-income economy, ...).

        • data.entity.oecdMember boolean

          Flag if country is an OECD member.

        • data.entity.resultsTimeSeriesAvailable boolean

          Flag if there is a time series available for the data result.

      • data.results array[object]

        Could also be an object instead of an array.

        • data.results.timestamp string(date)

          Date.

        • data.results.type string

          Flag if the data is based on historic, current or projected/forecasted data.

          Values are history, current, and projection.

        • data.results.score number

          Model risk score where higher values indicate higher risk with the exception of the SDG Index where a higher value indicates better SDG performance.

          Minimum value is 0, maximum value is 100.

        • data.results.regionalScore number

          Regional model risk score. Only available for the SDG Index.

          Minimum value is 0, maximum value is 100.

        • data.results.riskClassificationNumeric integer

          Model risk category (numeric) where higher values indicate higher risk.

          Values are 1, 2, 3, 4, and 5.

        • data.results.riskClassificationCategorical string

          Model risk category from very low to very high risk.

          Values are Very Low, Low, Medium, High, and Very High.

        • data.results.riskPoints integer

          Absolut number of risk points.

          Minimum value is 0.

        • data.results.riskPointsMax integer

          Maximum number of risk points possible based on available underlying data.

          Minimum value is 0.

        • data.results.ratingNumeric integer

          Numeric rating.

          Minimum value is 1, maximum value is 21.

        • data.results.ratingLetter string

          Letter rating.

          Values are AAA, AA+, AA, AA-, A+, A, A-, BBB+, BBB, BBB-, BB+, BB, BB-, B+, B, B-, CCC+, CCC, CCC-, CC - C, and D.

        • data.results.shareIndicatorsAvailable number

          Share of available data used for calculating the model risk score.

          Minimum value is 0, maximum value is 1.

        • data.results.dataQualityNumeric integer

          Data quality score where higher values indicate better data quality.

          Values are 1, 2, 3, 4, and 5.

        • data.results.dataQualityCategorical string

          Data quality category.

          Values are Very Poor, Poor, Medium, Good, and Very Good.

        • data.results.countryRank integer

          Risk rank.

        • data.results.countryUniverse integer

          Number of countries considered for risk rank.

Definition
GET https://countryrisk.io/api/v1/riskscores/{model}/
cURL example
curl \ -X GET https://countryrisk.io/api/v1/riskscores/aml/ \ -H "Content-Type: application/json"
Response example (200)
{ "model": { "description": "ESG Risk Score", "url": "https://www.countryrisk.io", "source": "CountryRisk.io Ltd", "version": "v1", "updateDate": "2019-11-20", "type": "ESG Risk Score" }, "data": [ { "entity": { "geoType": "country", "worldBankClassification": "High income", "countryCode": "SWE", "resultsTimeSeriesAvailable": true, "countryName": "Sweden", "regionName": "Europe & Central Asia", "oecdMember": true }, "results": [ { "dataQualityCategorical": "Very Good", "shareIndicatorsAvailable": 0.888, "score": 11.831, "countryUniverse": 186, "timestamp": "2019-12-31", "riskClassificationCategorical": "Very Low", "ratingLetter": "AA+", "ratingNumeric": 2, "riskClassificationNumeric": 1, "type": "current", "dataQualityNumeric": 5, "countryRank": 3 } ] } ] }

Risk scores by country

Get risk scores by model and country.

URL parameters
  • model Required / string

    Risk score model

    Values are aml, esg, sdg, and sovereign.

  • country_code Required / string

    Country code

Responses
  • 200 object

    Detailed risk scores by model for the specified country.

    • model object

      Risk model definition.

      • model.type string

        Risk model type.

      • model.version string

        Risk model version number.

      • model.updateDate string(date)

        Date of update.

      • model.description string

        Risk model description.

      • model.source string

        Risk model source.

      • model.url string(uri)

        Risk model url for further information.

    • entity object

      Geographical information.

      • entity.geoType string

        Geographic type (e.g. country, region, municipality, ...).

      • entity.countryCode string

        Country code following the ISO 3166-1 alpha-3 codes.

      • entity.countryName string

        Country name.

      • entity.regionName string

        Region name (e.g. Asia, Latin America, ...).

      • entity.worldBankClassification string

        World Bank income classification (e.g. low-income economy, lower-middle-income economy, ...).

      • entity.oecdMember boolean

        Flag if country is an OECD member.

      • entity.resultsTimeSeriesAvailable boolean

        Flag if there is a time series available for the data result.

    • results array[object]

      Could also be an object instead of an array.

      • results.timestamp string(date)

        Date.

      • results.type string

        Flag if the data is based on historic, current or projected/forecasted data.

        Values are history, current, and projection.

      • results.score number

        Model risk score where higher values indicate higher risk with the exception of the SDG Index where a higher value indicates better SDG performance.

        Minimum value is 0, maximum value is 100.

      • results.regionalScore number

        Regional model risk score. Only available for the SDG Index.

        Minimum value is 0, maximum value is 100.

      • results.riskClassificationNumeric integer

        Model risk category (numeric) where higher values indicate higher risk.

        Values are 1, 2, 3, 4, and 5.

      • results.riskClassificationCategorical string

        Model risk category from very low to very high risk.

        Values are Very Low, Low, Medium, High, and Very High.

      • results.riskPoints integer

        Absolut number of risk points.

        Minimum value is 0.

      • results.riskPointsMax integer

        Maximum number of risk points possible based on available underlying data.

        Minimum value is 0.

      • results.ratingNumeric integer

        Numeric rating.

        Minimum value is 1, maximum value is 21.

      • results.ratingLetter string

        Letter rating.

        Values are AAA, AA+, AA, AA-, A+, A, A-, BBB+, BBB, BBB-, BB+, BB, BB-, B+, B, B-, CCC+, CCC, CCC-, CC - C, and D.

      • results.shareIndicatorsAvailable number

        Share of available data used for calculating the model risk score.

        Minimum value is 0, maximum value is 1.

      • results.dataQualityNumeric integer

        Data quality score where higher values indicate better data quality.

        Values are 1, 2, 3, 4, and 5.

      • results.dataQualityCategorical string

        Data quality category.

        Values are Very Poor, Poor, Medium, Good, and Very Good.

      • results.countryRank integer

        Risk rank.

      • results.countryUniverse integer

        Number of countries considered for risk rank.

    • sections array[object]
      • sections.resultsTimeSeriesAvailable boolean

        Flag if there is a time series available for the section result.

      • sections.name string

        Name of risk section.

      • sections.reference string

        Reference of risk section.

      • sections.defaultWeight number

        Weight of risk section of overall risk score result.

        Minimum value is 0, maximum value is 1.

      • sections.description string

        Description of risk section.

      • sections.SDGnumber integer

        Reference to SDG number. Only available for SDG Index.

      • sections.results array[object]
        • sections.results.timestamp string(date)

          Date.

        • sections.results.type string

          Flag if the data is based on historic, current or projected/forecasted data.

          Values are history, current, and projection.

        • sections.results.score number

          Section risk score where higher values indicate higher risk with the exception of the SDG Index where a higher value indicates better SDG performance.

          Minimum value is 0, maximum value is 100.

        • sections.results.sdgColor string

          SDG color information. Only available for SDG Index.

        • sections.results.sdgColorInterpretation string

          SDG color interpretation. Only available for SDG Index.

        • sections.results.sdgTrendArrow string

          SDG trend information. Only available for SDG Index.

        • sections.results.sdgTrendInterpretation string

          SDG trend interpretation. Only available for SDG Index.

        • sections.results.riskClassificationNumeric integer

          Model risk category (numeric) where higher values indicate higher risk.

          Values are 1, 2, 3, 4, and 5.

        • sections.results.riskClassificationCategorical string

          Model risk category from very low to very high risk.

          Values are Very Low, Low, Medium, High, and Very High.

        • sections.results.riskPoints integer

          Absolut number of section risk points.

          Minimum value is 0.

        • sections.results.riskPointsMax integer

          Maximum number of section risk points possible based on available underlying data.

          Minimum value is 0.

        • sections.results.dataQualityNumeric integer

          Data quality score where higher values indicate better data quality.

          Values are 1, 2, 3, 4, and 5.

        • sections.results.dataQualityCategorical string

          Data quality category.

          Values are Very Poor, Poor, Medium, Good, and Very Good.

        • sections.results.countryRank integer

          Risk section rank.

        • sections.results.countryUniverse integer

          Number of countries considered for risk section rank.

        • sections.results.weight number

          Rescaled weight of risk section of overall risk score result based on available section results.

          Minimum value is 0, maximum value is 100.

    • indicators array[object]
      • indicators.resultsTimeSeriesAvailable boolean

        Flag if there is a time series available for the indicator.

      • indicators.name string

        Indicator name.

      • indicators.reference string

        Indicator reference.

      • indicators.shortName string

        Indicator short name.

      • indicators.source string

        Indicator source.

      • indicators.url string(uri)

        Indicator url.

      • indicators.description string

        Indicator description.

      • indicators.defaultWeight number

        Indicator weight in section result.

      • indicators.frequency string

        Indicator frequency (e.g. annual, monthly, ...).

      • indicators.unit string

        Indicator unit (e.g. millions, billions, kg, ...).

      • indicators.currency string

        Indicator currency (e.g. USD, GBP, ...).

      • indicators.lastUpdated string

        Indicator date of last update.

      • indicators.section string

        Reference to risk section.

      • indicators.scoring array[object]
        • indicators.scoring.threshold string

          Thresholds for indicator assessment to risk categories.

        • indicators.scoring.riskPoints number

          Risk points associated with risk categories.

      • indicators.applicableFlag string

        Information if the indicator is limited to certain country groups.

      • indicators.results array[object]
        • indicators.results.timestamp string(date)

          Date.

        • indicators.results.type string

          Flag if the data is based on historic, current or projected/forecasted data.

          Values are history, current, and projection.

        • indicators.results.score number

          Indicator risk score.

          Minimum value is 0, maximum value is 100.

        • indicators.results.riskClassificationNumeric integer

          Indicator risk category (numeric) where higher values indicate higher risk.

          Values are 1, 2, 3, 4, and 5.

        • indicators.results.riskClassificationCategorical string

          Indicator risk category from very low to very high risk.

          Values are Very Low, Low, Medium, High, and Very High.

        • indicators.results.riskPoints integer

          Indicator risk points based on underyling data and mapping to risk category.

          Minimum value is 0.

        • indicators.results.riskPointsMax integer

          Maximum number of risk points possible based on mapping to risk category.

          Minimum value is 0.

        • indicators.results.sdgColor string

          SDG color information. Only available for SDG Index.

        • indicators.results.sdgColorInterpretation string

          SDG color interpretation. Only available for SDG Index.

        • indicators.results.sdgTrendArrow string

          SDG trend information. Only available for SDG Index.

        • indicators.results.sdgTrendInterpretation string

          SDG trend interpretation. Only available for SDG Index.

        • indicators.results.countryRank integer

          Indicator risk rank.

        • indicators.results.countryUniverse integer

          Number of countries considered for indicator risk rank.

        • indicators.results.weight number

          Rescaled weight of indicator based on available data.

          Minimum value is 0, maximum value is 100.

        • indicators.results.data object

          Raw data information.

          • indicators.results.data.name array[string]

            Name of indicator or indicators. Could also be a single value instead of an array.

          • indicators.results.data.value array[]

            Value of indicator or indicators. Could also be a single value instead of an array.

Definition
GET https://countryrisk.io/api/v1/riskscores/{model}/{country_code}/
cURL example
curl \ -X GET https://countryrisk.io/api/v1/riskscores/aml/aut/ \ -H "Content-Type: application/json"
Response example (200)
{ "model": { "description": "ESG Risk Score", "url": "https://www.countryrisk.io", "source": "CountryRisk.io Ltd", "version": "v1", "updateDate": "2019-11-20", "type": "ESG Risk Score" }, "entity": { "geoType": "country", "worldBankClassification": "High income", "countryCode": "SWE", "resultsTimeSeriesAvailable": true, "countryName": "Sweden", "regionName": "Europe & Central Asia", "oecdMember": true }, "results": [ { "dataQualityCategorical": "Very Good", "shareIndicatorsAvailable": 0.888, "score": 11.831, "countryUniverse": 186, "timestamp": "2019-12-31", "riskClassificationCategorical": "Very Low", "ratingLetter": "AA+", "ratingNumeric": 2, "riskClassificationNumeric": 1, "type": "current", "dataQualityNumeric": 5, "countryRank": 3 } ], "sections": [ { "reference": "EconomicGrowthProspects", "results": [ { "dataQualityCategorical": "Very Good", "weight": 16.216, "timestamp": "2019-12-31", "riskClassificationCategorical": "Very Low", "riskPoints": 83, "score": 5.533, "riskClassificationNumeric": 1, "type": "current", "dataQualityNumeric": 5, "riskPointsMax": 1500 } ], "resultsTimeSeriesAvailable": true, "defaultWeight": 0.15, "name": "Economic Growth Prospects" }, { "reference": "Institutions", "results": [ { "dataQualityCategorical": "Good", "weight": 10.811, "timestamp": "2019-12-31", "riskClassificationCategorical": "Very Low", "riskPoints": 0, "score": 0, "riskClassificationNumeric": 1, "type": "current", "dataQualityNumeric": 4, "riskPointsMax": 700 } ], "resultsTimeSeriesAvailable": true, "defaultWeight": 0.1, "name": "Institutions & Governance" } ], "indicators": [ { "scoring": [ { "threshold": "< 50%", "riskPoints": 100 }, { "threshold": "< 100%", "riskPoints": 50 }, { "threshold": "< 150%", "riskPoints": 0 }, { "threshold": ">= 150%", "riskPoints": 10 } ], "name": "IMF Reserves Adequacy Ratio", "reference": "imf_ara_metric", "currency": null, "url": "http://www.imf.org/external/datamapper/ARA/index.html", "section": "ExternalDebtSustainability", "results": [ { "data": { "name": "IMF Reserves Adequacy Ratio", "value": null }, "riskPoints": null, "score": null, "timestamp": "2019-12-31", "type": "current", "riskPointsMax": null } ], "lastUpdated": "2019-11-18", "resultsTimeSeriesAvailable": false, "source": "International Monetary Fund", "frequency": "Annual", "shortName": "IMF Reserves Adequacy Ratio", "unit": "%", "description": "IMF Reserves Adequacy Ratio" }, { "scoring": [ { "threshold": "< 2", "riskPoints": 0 }, { "threshold": "< 4", "riskPoints": 25 }, { "threshold": "< 6", "riskPoints": 50 }, { "threshold": "< 8", "riskPoints": 75 }, { "threshold": ">= 8", "riskPoints": 100 } ], "name": "Hazard & Exposure Index", "reference": "HazardExposureIndex", "currency": null, "url": "http://inform-index.org/", "section": "Social", "results": [ { "data": { "name": "Hazard & Exposure Index", "value": 0.6 }, "riskPoints": 0, "score": 0, "timestamp": "2019-12-31", "type": "current", "riskPointsMax": 100 } ], "lastUpdated": "2019-11-18", "resultsTimeSeriesAvailable": true, "source": "INFORM", "frequency": "Annual", "applicableFlag": "All countries", "shortName": "Hazard & Exposure Index", "unit": "Index", "description": "The hazard & exposure dimension reflects the probability of physical exposure associated with specific hazards. There is no risk if there is no physical exposure, no matter how severe the hazard event is. Therefore, the hazard and exposure dimensions are merged into hazard & exposure dimension. As such it represents the load that the community has to deal with when exposed to a hazard event. The dimension comprises two categories: natural hazards and human-induced hazards, aggregated with the geometric mean, where both indexes carry equal weight within the dimension." } ] }

Country

Get country with current risk scores.

URL parameters
  • code Required / string

    Country code

Responses
  • 200 object

    A single Country with current risk scores.

    • name string

      Country name.

    • code string

      Country code.

    • riskscores array[object]
      • riskscores.model string

        Risk score model.

        Values are aml, esg, sdg, and sovereign.

      • riskscores.riskClassificationCategorical string

        Model risk category from very low to very high risk.

        Values are Very Low, Low, High, and Very High.

      • riskscores.timestamp string(date)

        Date.

      • riskscores.score number

        Model risk score where higher values indicate higher risk with the exception of the SDG Index where a higher value indicates better SDG performance.

Definition
GET https://countryrisk.io/api/v1/riskscores/country/{code}/
cURL example
curl \ -X GET https://countryrisk.io/api/v1/riskscores/country/aut/ \ -H "Content-Type: application/json"
Response example (200)
{ "name": "Sweden", "code": "SWE", "riskscores": [ { "timestamp": "2019-12-31", "model": "sovereign", "score": 7.831, "riskClassificationCategorical": "Very Low" }, { "timestamp": "2019-12-31", "model": "esg", "score": 11.831, "riskClassificationCategorical": "Very Low" }, { "timestamp": "2019-11-19", "model": "aml", "score": 4.12, "riskClassificationCategorical": "Very Low" }, { "timestamp": "2019-08-31", "model": "sdg", "score": 85, "riskClassificationCategorical": "Very low" } ] }