Country Risk Public API
1.0.0

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 Dec 7, 2022.

Base URL
https://app.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://app.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

Risk score models

GET /configuration/riskscoremodels/

Get risk score models.

Responses

  • 200 array[object]

    A list of risk score models.

    • title string

      Title

    • Description

    • source string

      Source

    • code string

      Code (see values below) or custom code (if you have access to bespoke risk scores)

      Values are aml, esg, sdg, sovereign, or supplychainrisk.

GET /configuration/riskscoremodels/
curl \
 -X GET https://app.countryrisk.io/api/v1/configuration/riskscoremodels/ \
 -H "Authorization: $API_KEY"
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"
  },
  {
    "source": "CountryRisk.io Ltd",
    "code": "supplychainrisk",
    "description": "Supply Chain Country Risk Score",
    "title": "CountryRisk.io Supply Chain Country Risk Score"
  }
]

Countries

GET /configuration/countries/

Get countries.

Query parameters

  • code string

    Country code

  • name string

    Country name

  • model string

    Ordering

    Values are code, -code, name, or -name. Default value is code.

Responses

  • 200 array[object]

    A list of countries.

    • name string

      Country name.

    • code string

      Country code.

      Minimum length is 3, maximum length is 3.

GET /configuration/countries/
curl \
 -X GET https://app.countryrisk.io/api/v1/configuration/countries/ \
 -H "Authorization: $API_KEY"
Response example (200)
[
  {
    "name": "Australia",
    "code": "AUS"
  },
  {
    "name": "Austria",
    "code": "AUT"
  },
  {
    "name": "Sweden",
    "code": "SWE"
  }
]

Risk scores

GET /riskscores/{model}/

Get risk scores by model.

Path parameters

  • model string Required

    Risk score model (see values below) or custom model (if you have access to bespoke risk scores)

    Values are aml, esg, sdg, sovereign, or supplychainrisk.

Query parameters

  • Country code

  • Country name

  • ordering string

    Ordering

    Values are country_code, -country_code, country_name, or -country_name. Default value is country_code.

Responses

  • 200 object

    A list of risk scores.

    • model object

      Risk model definition.

    • data array[object]
      • entity object

        Geographical information.

      • results array[object]

        Risk score information.

        • timestamp string(date)

          Date.

        • type string

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

          Values are history, current, or projection.

        • 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.

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

          Minimum value is 0, maximum value is 100.

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

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

        • Model risk category from very low to very high risk.

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

        • riskPoints integer

          Absolut number of risk points.

          Minimum value is 0.

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

          Minimum value is 0.

        • Numeric rating.

          Minimum value is 1, maximum value is 21.

        • 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, or D.

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

          Minimum value is 0, maximum value is 1.

        • Data quality score where higher values indicate better data quality.

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

        • Data quality category.

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

        • Risk rank.

        • Number of countries considered for risk rank.

GET /riskscores/{model}/
curl \
 -X GET https://app.countryrisk.io/api/v1/riskscores/aml/ \
 -H "Authorization: $API_KEY"
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 /riskscores/{model}/{country_code}/

Get risk scores by model and country.

Path parameters

  • model string Required

    Risk score model (see values below) or custom model (if you have access to bespoke risk scores)

    Values are aml, esg, sdg, sovereign, or supplychainrisk.

  • country_code string Required

    Country code

Responses

  • 200 object

    Detailed risk scores by model for the specified country.

    • model object

      Risk model definition.

    • entity object

      Geographical information.

    • results array[object]

      Risk score information.

      • timestamp string(date)

        Date.

      • type string

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

        Values are history, current, or projection.

      • 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.

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

        Minimum value is 0, maximum value is 100.

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

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

      • Model risk category from very low to very high risk.

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

      • riskPoints integer

        Absolut number of risk points.

        Minimum value is 0.

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

        Minimum value is 0.

      • Numeric rating.

        Minimum value is 1, maximum value is 21.

      • 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, or D.

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

        Minimum value is 0, maximum value is 1.

      • Data quality score where higher values indicate better data quality.

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

      • Data quality category.

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

      • Risk rank.

      • Number of countries considered for risk rank.

    • sections array[object]

      Risk section information.

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

      • name string

        Name of risk section.

      • Reference of risk section.

      • Weight of risk section of overall risk score result.

        Minimum value is 0, maximum value is 1.

      • Description of risk section.

      • SDGnumber integer

        Reference to SDG number. Only available for SDG Index.

      • results array[object]

        Section risk score information.

        • timestamp string(date)

          Date.

        • type string

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

          Values are history, current, or projection.

        • 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.

        • sdgColor string

          SDG color information. Only available for SDG Index.

        • SDG color interpretation. Only available for SDG Index.

        • SDG trend information. Only available for SDG Index.

        • SDG trend interpretation. Only available for SDG Index.

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

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

        • Model risk category from very low to very high risk.

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

        • riskPoints integer

          Absolut number of section risk points.

          Minimum value is 0.

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

          Minimum value is 0.

        • Data quality score where higher values indicate better data quality.

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

        • Data quality category.

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

        • Risk section rank.

        • Number of countries considered for risk section rank.

        • 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]

      Indicator information.

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

      • name string

        Indicator name.

      • Indicator reference.

      • Indicator short name.

      • source string

        Indicator source.

      • url string(uri)

        Indicator url.

      • Indicator description.

      • Indicator weight in section result.

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

      • unit string

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

      • currency string

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

      • Indicator date of last update.

      • section string

        Reference to risk section.

      • scoring array[object]

        Indicator scoring information.

        • Thresholds for indicator assessment to risk categories.

        • Risk points associated with risk categories.

      • Information if the indicator is limited to certain country groups.

      • results array[object]

        Indicator risk score information.

        • timestamp string(date)

          Date.

        • type string

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

          Values are history, current, or projection.

        • score number

          Indicator risk score.

          Minimum value is 0, maximum value is 100.

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

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

        • Indicator risk category from very low to very high risk.

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

        • riskPoints integer

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

          Minimum value is 0.

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

          Minimum value is 0.

        • sdgColor string

          SDG color information. Only available for SDG Index.

        • SDG color interpretation. Only available for SDG Index.

        • SDG trend information. Only available for SDG Index.

        • SDG trend interpretation. Only available for SDG Index.

        • Indicator risk rank.

        • Number of countries considered for indicator risk rank.

        • weight number

          Rescaled weight of indicator based on available data.

          Minimum value is 0, maximum value is 100.

        • data object

          Raw data information.

GET /riskscores/{model}/{country_code}/
curl \
 -X GET https://app.countryrisk.io/api/v1/riskscores/aml/aut/ \
 -H "Authorization: $API_KEY"
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 /riskscores/country/{code}/

Get country with current risk scores.

Path parameters

  • code string Required

    Country code

Responses

  • 200 object

    A single Country with current risk scores.

    • name string

      Country name.

    • code string

      Country code.

      Minimum length is 3, maximum length is 3.

    • riskscores array[object]
      • model string

        Risk score model (see values below) or custom model (if you have access to bespoke risk scores).

        Values are aml, esg, sdg, sovereign, or supplychainrisk.

      • Model risk category from very low to very high risk.

        Values are Very Low, Low, High, or Very High.

      • timestamp string(date)

        Date.

      • 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.

GET /riskscores/country/{code}/
curl \
 -X GET https://app.countryrisk.io/api/v1/riskscores/country/aut/ \
 -H "Authorization: $API_KEY"
Response example (200)
{
  "name": "Sweden",
  "code": "SWE",
  "riskscores": [
    {
      "timestamp": "2021-12-31",
      "model": "sovereign",
      "score": 11.12,
      "riskClassificationCategorical": "Very Low"
    },
    {
      "timestamp": "2021-12-31",
      "model": "esg",
      "score": 11.71,
      "riskClassificationCategorical": "Very Low"
    },
    {
      "timestamp": "2021-11-19",
      "model": "aml",
      "score": 3.98,
      "riskClassificationCategorical": "Very Low"
    },
    {
      "timestamp": "2021-08-31",
      "model": "sdg",
      "score": 85.61,
      "riskClassificationCategorical": "Very low"
    },
    {
      "timestamp": "2022-04-10",
      "model": "supplychainrisk",
      "score": 4.82,
      "riskClassificationCategorical": "Very low"
    }
  ]
}