Integrate third-party country risk assessment data – API and SDK guide

Background

Safeture supports adding third-party data sources, called Content Producers, to the Safeture Platform. Due to Safeture’s dynamic structure, the risk levels, risk categories, and risk assessment data can be updated at any moment. So, when handling the data, the knowledge that some data might be removed or added must be taken into consideration during implementation.

It is essential to make sure that mapping is possible when dealing with a new risk assessment methodology and mapping of data. Such controls can be done by checking if the cached risk levels or risk categories that are out of date and making sure that the UUID is valid for the risk assessment, or your script might break.

When using a typed language such as Swift, a good practice is to check that the property contains data. If data can not be parsed during the mapping process, the property will either be an empty array or a null property object.

Safeture APIs

Detailed information about our API can be found here:

https://cdn.safeture.com/platform/apidoc/

All mentioned API: s requires a basic login token to get access.

---

1. Subscription Data

Start by checking from which Content Producers you have access to retrieve risk assessment data. This is done via the subscriptions API. 

[GET] – Subscriptions

api.safeture.com/contentproducer/subscriptions

Response example:

"data": [ {
"contentproducerid": "SAFETURE",
"contenttypeid": "RISK_ASSESSMENT",
"allowcontentoverride": false,
"rebrandable": true
} ]

Copy

For now, allowcontentoverride and rebrandable can be ignored. But in the example above, we see that the risk assessment data comes from Safeture.

---

2. Risk Assessment Data from Content Producer

The next step is to get Safeture’s (or which risk assessment content producer you have access to) risk levels and risk categories. To do that we use:

[GET] – Risk levels

api.safeture.com/riskassessment/{contentproducerid}/risklevels
Response example:

"data": [
        {
            "contentproducerid": "SAFETURE",
            "riskleveluuid": "0607d9a0-d7ef-11eb-bda3-43553f393972",
            "risklevelid": "NEGLIGIBLE",
            "risklevelvalue": 1,
            "risklevelname": "Negligible",
            "risklevelcolor": "#8CC740"
        },
        {
            "contentproducerid": "SAFETURE",
            "riskleveluuid": "0607ed3c-d7ef-11eb-bda3-2fbb431431f2",
            "risklevelid": "LOW",
            "risklevelvalue": 2,
            "risklevelname": "Low",
            "risklevelcolor": "#D2E038"
        }
]

Copy

[GET] – Risk categories
api.safeture.com/riskassessment/{contentproducerid}/riskcategories

Response example:

"data": [
        {
            "contentproducerid": "SAFETURE",
            "riskcategoryuuid": "060833dc-d7ef-11eb-bda3-cb4da9f8902b",
            "riskcategoryid": "CIVIL UNREST",
            "riskcategoryname": "Civil Unrest",
            "description": "",
            "icon": "data:image/png;base64,iVBORw0KSUhEU…..",
            "weight": 1
        },
        {
            "contentproducerid": "SAFETURE",
            "riskcategoryuuid": "06081618-d7ef-11eb-bda3-6f44ef9e558f",
            "riskcategoryid": "CRIME",
            "riskcategoryname": "Crime",
            "description": "",
            "icon": "data:image/png;base64,iVBORw0KSUhEU…",
            "weight": 1
        }
]

Copy

---

3. Region Risk Assessment Data

The next step is to get the country risk assessment.

Here you can choose between two options:

(Viable for most API users) Read data from your predefined content producer for risk information that is set up in the platform. (If you have multiple subscriptions from different content producers that provides risk assessment and want to get the risk assessment data for your official provider). Then use the API call below.

[GET]

api.safeture.com/regionriskassessment/region/{regionid}

If you subscribe to multiple risk providers use below api call to get specific data from subscribed content producer:

[GET]

api.safeture.com/regionriskassessment/{contentproducerid}/region/{regionid}

Response example:

"data": {
    "producername": "Safeture",
    "contentproducerid": "SAFETURE",
    "regionid": "Sweden",
    "regionname": "Sweden",
    "iso3166_1": "SE",
    "description": "",
    "trend": 0,
    "trendprojection": 0,
    "riskleveluuid": "0607ed3c-d7ef-11eb-bda3-2fbb431431f2",
    "risk_assessment": [
        {
            "riskcategoryuuid": "060833dc-d7ef-11eb-bda3-cb4da9f8902b",
            "riskleveluuid": "0607ed3c-d7ef-11eb-bda3-2fbb431431f2",
            "riskassessmentbasic": "<p>Sweden experiences&nbsp; p>",
            "trend": 0,
            "trendprojection": 0
        },
        {
            "riskcategoryuuid": "06081618-d7ef-11eb-bda3-6f44ef9e558f",
            "riskleveluuid": "0607d9a0-d7ef-11eb-bda3-43553f393972",
            "riskassessmentbasic": "<p>Major tourist attractions, urban centres</p>",
            "trend": 0,
            "trendprojection": 0

    ],
    "trendinfo": {
        "showtrend": 0,
        "showtrendprojection": 0,
        "trenddescription": "The general direction or trend in which.",
        "trendprojectiondescription": "The projected trend is a prediction of future."
    }
}

Copy

Both API calls will return the same data structure. The only difference is the data it contains.

---

4. Read Compiled Region Card

The country risk assessment data is also present in the read compiled region card. In the response call under the param “tree”

[GET]

api.safeture.com/regioncard/getcompiled?language={language}&regionid={regionid}

Response example:

{
    "regioncard": {
        "region": {
           ...
        },
        "providers": [
            ...
        ],
        "tree": [
            ...
        ],
        "viewid": "…",
        "structure": [
            ...
        ]
    }
}

Copy

In the object with the heading id “safetureSafety”, the parameter’s children will contain the new risk assessment object with a heading id “safetyAndSecurity-Risk Assessment”. Inside the data parameter, the same risk assessment structure as mentioned under the section above country risk assessment data will be found.

Note that your risk assessment data might be structured under a different heading id than safetureSafety, but the general structure will be the same. 

An example of what it can look like is shown below:

"regioncard": {
        "region": {
            ...
        },
        "providers": [
            ...
        ],
        "tree": [
            {
                "headingid": "safetureSafety",
                "payloadtype": "text/html",
                "vieworder": 2,
                "title": "Safety",
                "children": [
                    {
                        "headingid": "safetyAndSecurity-Risk Assessment",
                        "payloadtype": "application/json,gws/risk-assesments",
                        "vieworder": 1,
                        "title": "Risk Assessment",
                        "data": [
                            {
                                "producername": "Safeture",
                                "contentproduceruuid": "060789aa-d7ef-11eb-bda3-3b48e708c2e5",
                                "regionid": "Sweden",
                                "regionname": "Sweden",
                                "iso3166_1": "SE",
                                "description": "",
                                "trend": 0,
                                "trendprojection": 0,
                                "riskleveluuid": "0607ed3c-d7ef-11eb-bda3-2fbb431431f2",
                                "risk_assessment": [
                                    ...
                                ],
                                "trendinfo": {
                                    "showtrend": 0,
                                    "showtrendprojection": 0,
                                    "trenddescription": "",
                                    "trendprojectiondescription": ""
                                }
                            }
                        ]
                    },
                    {
                        "headingid": "safetyAndSecurity-Threat Assessment",
                        "payloadtype": "application/json,gws/threat-assesments",
                        "vieworder": 1,
                        "title": "Threat Assessment",
                        "data": [
                            ...
                        ]
                    },
                    {
                      ...
                    }
                ]
            },
            {
                "headingid": "safetureAlerts",
                "payloadtype": "application/json,gws/events",
                "vieworder": 3,
                "title": "Alerts",
                "data": [
                    ...
                ]
            }
        ],
        "structure": [
            ...
        ]
    }
}

Copy

---

5. Mapping the UUIDs

Now that we have the needed data, it is time to map it correctly. The data we got from risk level and risk categories API will be added to the risk assessment object. The reason for doing so is not to have to send the same data repeatedly. Instead, we append the risk level data and risk category data to the region risk assessment object.

Use X uuid & Y uuid respectively for matching risk level and risk category as explained below: 

1. Firstly, get all the content producer’s risk levels and categories. We already have them saved and cached.
2. Check that you have all the data to start the mapping.
3. Make a dictionary of the risk levels with UUID and the same with risk categories for a quicker look-up.
4. Add the risk level data to the region risk assessment with the risk level UUID.
5. Note that this is built dynamically, meaning that the risk level or risk categories can potentially be removed by the content producer at any time. Therefore, a check if data mapping is possible is needed every time.
6. Check that the region has risk assessments added to it. Your content producer might have made risk assessments for subregions within a country or the country as a whole. 
7. Loop the risk assessment array with a filter so we will not return it to the final array if we can’t map the data. Because Showing UUID is not readable for the user.
8. Override the new, mapped risk assessment.
9. Finally, return the regionriskassessemnt object with the mapped data.

---

6. SDK

When using the SDK solution, there is no need to take care of the mapping part, all that is handled within the SDK. Your predefined content producer will provide the risk assessment data. If you subscribe to multiple content producers for risk information, your predefined one is the one that will be sent to the SDK for processing.

The head of files of the IOS SDK will be shown below. 

To get the new risk assessment data for a country, you now have a new property risk assessment available in the region information object. 

7. SDK Risk Assessment Structure

This new object contains the following and will replace the threatassessment property that will now be deprecated in the future version of the SDK.

@interface RiskAssessment : NSObject
/**
 * The Content producer that created the risk assessment data
 */
@property(readonly, nullable) ContentProducer* contentProducer;
/**
 * The summary risk assessment for the region it describes
 */
@property(readonly, nullable) SummaryAssessment* summaryAssessment;
/**
 * All the risk categories, risk levels and description about the region
 */
@property(readonly, nullable) NSArray<Assessment*>* assessmnets;

@end

Copy

Let’s go thought each one of them and see what they contain.

Content Producer

The property content producer contains the following:

@interface ContentProducer : NSObject

/**
    The unique id for this content producer
 */
@property (readonly, nonnull) NSString* contentProducerUniqueId;

/**
    The id of the content producer
 */
@property (readonly, nonnull) NSString* contentProducerId;

/**
    The name of the content producer
 */
@property (readonly, nonnull) NSString* contentProducerName;
/**
    The description about the content producer
 */
@property (readonly, nonnull) NSString* contentProducerDescription;

/**
    The icon/ logo for the content producers
 */
@property (readonly, nonnull) UIImage* icon;

/**
    Contains all the permissions of the content that the contnent producer allows of its content
 */
@property(readonly, nullable) NSArray<ContentProducerPermission*>* contentPermissions;


@end

Copy

This is useful if you want to showcase who the content is created by. The “contentPermission” contains info on how you are allowed to use their content. As for now it only contains what content type is brandable or not. i.e., If they allow you to rebrand its content or not.

Summary Assessment

This property contains the summary risk information about the country. This property contains the following:

@interface SummaryAssessment : NSObject

/**
 Get the risk level for this summary of the assessment
 */
@property(readonly, nonnull) RiskLevel* riskLevel;

/**
 Get a summary description about the regions risk assessment.
 */
@property(readonly, nonnull) NSString* summaryDescription;

/**
 Get a general direction or trend in which a risk develops or changes over time. defined by the content producer.
 */
@property(readonly) NSInteger trend;

/**
 Get a projected trend, that is a prediction of future change.  defined by the content producer.
 */
@property(readonly) NSInteger trendProjection;

@end

Copy

Additional information:

• Risk level property will be described further down in this document.
• The summary description will be in the language that the SDK has set as used language and machine translation is active. Otherwise, English / the default language that the content producer has written the text in.
• Trend and trend projection are defined by the content producer and not always used and have a default value of 0.

Assessments

The assessment property contains all the risks that a country has. The property looks as follows:

@interface Assessment : NSObject
/**
 Get the risk level for this Category assessment
 */
@property(readonly, nonnull) RiskLevel* riskLevel;

/**
 Get the Category for this assessment
 */
@property(readonly, nonnull) RiskCategory* riskCategory;

/**
 Get the description about this assessment
 */
@property(readonly,nonnull) NSString* assessmentDescription;

/**
 Get a general direction or trend in which a risk develops or changes over time. defined by the content producer.
 */
@property(readonly) NSInteger trend;
/**
 Get a projected trend, that is a prediction of future change.  defined by the content producer.
 */
@property(readonly) NSInteger trendProjection;

@end

Copy

Additional information:

• Risk category property will be described further down in this document
• The assessment description will be in the language that the SDK has set as used language and machine translation is active. Otherwise, English / the default language the content producer has written the text in.
• The trend and trend projection are defined by the content producer and not always used and have a default value of 0.

Risk Level

This property contains the following:

@interface RiskLevel : NSObject

/**
    The uniqe id for the risk level.
 */
@property (readonly, nonnull) NSString* riskLevelUniqueId;

/**
    The ID for the risk level name
 */
@property (readonly, nonnull) NSString* riskLevelId;

/**
 The name of the risk level in the language specified
 */
@property (readonly, nonnull) NSString* riskLevelName;

/**
 The color of the risk level.
 */
@property (readonly, nonnull) UIColor* riskLevelColor;

/**
    A number descibing the risk level to others
 */
@property (readonly) NSInteger riskLevelValue;


@end

Copy

Risk Category

This property contains the following:

@interface RiskCategory : NSObject

/**
    The uniqe id for the risk category
 */
@property (readonly, nonnull) NSString* categoryUniqueId;

/**
    The ID for the risk category name
 */
@property (readonly, nonnull) NSString* categoryId;

/**
    The risk category name, in the language specified
 */
@property (readonly, nonnull) NSString* categoryName;


/**
 The description of the risk category, in the language specified
 */
@property (readonly, nonnull) NSString* categoryDescription;

/**
    A number descibing the priority of this type compared to others
 */
@property (readonly) NSInteger weight;


/**
 An image representing the risk category
 */
@property (readonly, nonnull) UIImage* icon;


@end