API - Postman Examples

This article describes how you can use Postman to access the Safety Pool (SP) API to retrieve Scenarios, Test Suites, and Ontologies. 

The Postman platform allows you to call APIs without having to write any code.

Safety Pool API Location

The root location of the API can be found at: https://live.safetypooldb.ai/api. The API is only accessible via HTTPS and requires TLS v1.2 or higher. Currently, the API only allows read-access to the database.

Authentication

In order to use the API to access data, an API Key must have been obtained first (Refer to this article on how to generate the API Key). The API methods that access data are secured and require a JWT Bearer token to be passed with each request. To start an API session, the createtoken method must be called with a valid API Key using: /createtoken/{apiKey}. Note that you need to send a POST request. If your API key is valid (HTTP status code is 200), it will return a JSON object that includes a token and its expiry date, as shown in the below image. 

The obtained token must then be passed as a Bearer Token on subsequent calls to secured API methods. The token needs to be copied to the 'Bearer Token' type in the 'Authorization' tab. This token needs to be passed with each GET request as seen in the below image.

Accessing Scenarios

Retrieving a Scenario

To retrieve a scenario via the API you first need to know the Unique Reference Number (URN) of the scenario which can be found by either viewing the scenario in Safety Pool or using the scenario URNs returned from other API calls. To retrieve a scenario you need to make the following GET request passing the URN as the scenarioId : /scenarios/{scenarioId}.

Below is a sample JSON result for the scenario Id: "45b3cae7-5ca6-450d-ad49-1141be15c24b". Note that the scenario data is returned in the ASAM OpenLabel file format and that the actual scenario definition is contained within the 'scenarioDefnition' tag section in the WMG SDL Level 2 Language.

{
    "openlabel": {
        "metadata": {
            "schema_version": "1.0.0"
        },
        "ontologies": {
            "0": {
                "uri": "https://live.safetypooldb.ai/api/ontologies/v1"
            },
            "1": {
                "uri": "https://openlabel.asam.net/V1-0-0/ontologies/openlabel_ontology_scenario_tags.ttl"
            }
        },
        "tags": {
            "0": {
                "type": "LaneMarkingBrokenLine",
                "ontology_uid": "0"
            },
            "1": {
                "type": "HazardMajor",
                "ontology_uid": "0"
            },
            "2": {
                "type": "scenarioUniqueReference",
                "ontology_uid": "1",
                "tag_data": {
                    "text": [
                        {
                            "type": "value",
                            "val": "45b3cae7-5ca6-450d-ad49-1141be15c24b"
                        }
                    ]
                }
            },
            "3": {
                "type": "scenarioParentReference",
                "ontology_uid": "1",
                "tag_data": {
                    "text": [
                        {
                            "type": "value",
                            "val": "f456d447-057b-4955-b154-34cd99d601d9"
                        }
                    ]
                }
            },
            "4": {
                "type": "scenarioDescription",
                "ontology_uid": "1",
                "tag_data": {
                    "text": [
                        {
                            "type": "value",
                            "val": "stat19_1_10086"
                        }
                    ]
                }
            },
            "5": {
                "type": "scenarioVersion",
                "ontology_uid": "1",
                "tag_data": {
                    "text": [
                        {
                            "type": "value",
                            "val": "2.0"
                        }
                    ]
                }
            },
            "6": {
                "type": "scenarioCreatedDate",
                "ontology_uid": "1",
                "tag_data": {
                    "text": [
                        {
                            "type": "value",
                            "val": "2022-05-25 10:32:19Z"
                        }
                    ]
                }
            },
            "7": {
                "type": "scenarioDefinition",
                "ontology_uid": "1",
                "tag_data": {
                    "text": [
                        {
                            "type": "value",
                            "val": "VERSION: 8.1\nEXTENSION: None\nAUTHOR: 'WMG, Intelligent Vehicles - V&V Team (https://warwick.ac.uk/fac/sci/wmg/research/cav/vandv/)'\n\nSCENERY ELEMENTS:\nDO: Map - roads and junctions network [Network1] as:\nJunctions:\nYJ1: Junction type [Y-Junction] as [YJ1] which has [No] connection control and [3] connections with [R1, R2, R3] \nAngles between roads [R1 -> R2, R1 -> R3, R2 -> R3][145 to 155, 175 to 185, 25 to 35]\nRoad lane connections [R1.L1 -> R2.L1, R1.L1 -> R3.L1, R1.L2 -> R3.L2, R1.L3 -> R3.L3]\nDimensions [Width: 10 to 12, Depth: 10 to 12]\n\nRoads:\nR1:START\nRoad type [Motorway] as [R1] with zone as [N/A] AND speed limit of [60] in an [Urban] environment with \nNumber of lanes [3] as [R1.L1, R1.L2, R1.L3]\nRoad traffic direction [Left-handed]\nLane type [Traffic lane]\nLane markings [Broken line]\nRoad surface type [Uniform] with surface condition [Dry] \nHorizontal road geometry [Straight] \nVertical road geometry [Level plane]\nTransverse road geometry [Divided] \nRoadway edge features [Shoulder (grass)]\nLength [230 to 280] AND Lane width [3.4 to 3.7] \nEND\nR2:START\nRoad type ['Slip road'] as [R2] with zone as [N/A] AND speed limit of [60] in an [Urban] environment with \nNumber of lanes [1] as [R2.L1]\nRoad traffic direction [Left-handed]\nLane type [Traffic lane]\nLane markings [Broken line]\nRoad surface type [Uniform] with surface condition [Dry] \nHorizontal road geometry [Straight] \nVertical road geometry [Level plane]\nTransverse road geometry [Divided] with [No] roadside feature\nRoadway edge features [Shoulder (grass)]\nLength [110 to 160] AND Lane width [3.4 to 3.7] \nEND\nR3:START\nRoad type [Motorway] as [R3] with zone as [N/A] AND speed limit of [60] in an [Urban] environment with\nNumber of lanes [3] as [R3.L1, R3.L2, R3.L3]\nRoad traffic direction [Left-handed]\nLane type [Traffic lane]\nLane markings [Broken line]\nRoad surface type [Uniform] with surface condition [Dry] \nHorizontal road geometry [Straight] \nVertical road geometry [Level plane]\nTransverse road geometry [Undivided] \nRoadway edge features [Shoulder (grass)]\nLength [230 to 280] AND Lane width [3.4 to 3.7] \nEND\n\nDYNAMIC ELEMENTS:\nINITIAL: Vehicle [Ego] in [R2.L1] \n AND Vehicle [V2] in [R2.L1] AND at relative position [R] with relative heading angle [-5 to 5] to [Ego]\n AND Global timer [T1] = [0]\nWHEN: [Ego] is [Going_Ahead] \nDO: [V2]\nPHASE 1: [Drive_Towards] [-, 46 to 56, 1 to 2][Ego: 1 to 11, R]\nEND\n\t\t\t\nENVIRONMENT ELEMENTS:\nDO: [Env1]\nWind [3.4 to 5.4]\nCloudiness [1 to 2]\nRainfall [None: N/A]\nSnowfall [Heavy Snow : 0 to 0.5]\nTime of the day [00:00 to 03:00]\nIllumination [Day] with [Sun] as light source at [10 to 30] degree elevation AND [R] position"
                        }
                    ]
                }
            },
            "8": {
                "type": "scenarioDefinitionLanguageURI",
                "ontology_uid": "1",
                "tag_data": {
                    "text": [
                        {
                            "type": "value",
                            "val": "https://warwick.ac.uk/fac/sci/wmg/research/cav/vandv/lang/sdl/level2/v8.1"
                        }
                    ]
                }
            },
            "9": {
                "type": "ownerName",
                "ontology_uid": "1",
                "tag_data": {
                    "text": [
                        {
                            "type": "value",
                            "val": "WMG"
                        }
                    ]
                }
            },
            "10": {
                "type": "licenseURI",
                "ontology_uid": "1",
                "tag_data": {
                    "text": [
                        {
                            "type": "value",
                            "val": "https://live.safetypooldb.ai/identity/scriptlicense"
                        }
                    ]
                }
            }
        }
    }
}

Retrieving Scenario Files

To obtain a list of files which are associated with a scenario, you need to send a GET request with /scenarios/{scenarioId}/filelist :

Below is a sample JSON result for the file list of the above scenario.

[
    {
        "fileId": "172e4bcc-b63e-447c-b0ba-7a13f9161102",
        "name": "a5327c50-203e-4e59-822c-78d6a0e0617f.xosc",
        "size": 11450
    },
    {
        "fileId": "6cbe192a-60ce-44c8-baf4-97d57f223197",
        "name": "a5327c50-203e-4e59-822c-78d6a0e0617f.xodr",
        "size": 1580
    },
    {
        "fileId": "b8807ad6-f613-4928-b330-c4d8319cc4ee",
        "name": "ALKS_FollowLeadVehicleEmergencyBrake.mp4",
        "size": 692931
    }
]

In order to retrieve one of the files make a GET request with /scenarios/{scenarioId}/files/{fileId}: 

Accessing Test Suites

Retrieving all Test Suites

To retrieve a list of all of the Test Suites accessible for you organisation, you need to send a GET request using /testsuites : 

Below is a sample JSON result of a request to Test Suites. As you can see, for each Test Suite there is a list of scenario URNs which can be used with the /scenarios/{scenarioId} method to retrieve individual scenarios. 

[
    {
        "testsuiteid": 1,
        "name": "Testing",
        "scenarios": [
            "45b3cae7-5ca6-450d-ad49-1141be15c24b",
            "928351c3-caad-439d-abe9-fad40e7b5377",
            "59c9bdfe-799a-4e1f-a15b-37846a45c0c6",
            "111fe686-3615-4a4f-b7a2-4bdd1a8ec3eb",
            "a29bf01b-7838-4c56-ac40-739c0b178500",
            "587d523c-4178-4e9c-aa85-a624cf76c9a3"
        ]
    },
    {
        "testsuiteid": 8,
        "name": "Roundabouts",
        "scenarios": [
            "8cc4780e-8478-4aab-8a42-6880a0813fba",
            "85818cb2-c0aa-4c17-af2e-2ead2200ffa9",
            "2751823c-c49c-42aa-b525-2c176b9da83f",
            "2f2f908e-16fb-4788-b379-a672ea7e9d51"
        ]
    },
    {
        "testsuiteid": 52,
        "name": "Test 7",
        "scenarios": []
    },
    {
        "testsuiteid": 53,
        "name": "Test 10",
        "scenarios": [
            "ccf96fcf-4b33-4dbb-87a2-c7c531435a65"
        ]
    },
    {
        "testsuiteid": 55,
        "name": "ODD",
        "scenarios": [
            "59c9bdfe-799a-4e1f-a15b-37846a45c0c6",
            "6f55b674-6d6e-452b-92ca-cc1ac8c74d3d"
        ]
    },
    {
        "testsuiteid": 76,
        "name": "Pedestrian Crossing",
        "scenarios": [
            "7a0c4365-7d22-400e-9c0a-aee341a3c99b",
            "556199ac-ac81-48d1-8cfc-7a833048c00d",
            "8e4a1b1d-a98d-41cc-a728-bb0fd3c8a3ba"
        ]
    }
]

Retrieving a Test Suite

To retrieve an individual Test Suite, you need to send a GET request with /testsuites/{testsuiteId} by specifying the ID of the Test Suite which can be found either by viewing the Test Suite details in Safety Pool or by using the IDs returned from other API methods. 

Below is a sample JSON result for the testsuite ID: "1"

{
    "testsuiteid": 1,
    "name": "Testing",
    "scenarios": [
        "45b3cae7-5ca6-450d-ad49-1141be15c24b",
        "928351c3-caad-439d-abe9-fad40e7b5377",
        "59c9bdfe-799a-4e1f-a15b-37846a45c0c6",
        "111fe686-3615-4a4f-b7a2-4bdd1a8ec3eb",
        "a29bf01b-7838-4c56-ac40-739c0b178500",
        "587d523c-4178-4e9c-aa85-a624cf76c9a3"
    ]
}

Safety Pool Scenario Database Tagging Ontology

To retrieve the Safety Pool tagging ontology, you need to send a GET request with /ontologies/v1: 

Below is a sample result for Safety Pool tagging ontology in Turtle format.

# Safety Pool DB V1.0 Scenario Tagging Ontology
# Generated: 2022-09-22 12:14:46Z

@base <https://live.safetypooldb.ai/api/ontologies/v1/> .
@prefix asam: <https://openlabel.asam.net/V1-0-0/ontologies/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<AccidentCauseGod> a rdfs:Class ;
	rdfs:label "Act of God" ;
	rdfs:subClassOf <MetaAccidentCause> .

<AccidentCauseAnimal> a rdfs:Class ;
	rdfs:label "Animal" ;
	rdfs:subClassOf <MetaAccidentCause> .

<AccidentCauseMechanical> a rdfs:Class ;
	rdfs:label "Mechanical" ;
	rdfs:subClassOf <MetaAccidentCause> .

<AccidentCauseAi> a rdfs:Class ;
	rdfs:label "AI" ;
	rdfs:subClassOf <MetaAccidentCause> .

<AccidentCauseHuman> a rdfs:Class ;
	rdfs:label "Human" ;
	rdfs:subClassOf <MetaAccidentCause> .

<TestEnvironmentTrack> a rdfs:Class ;
	rdfs:label "Test track" ;
	rdfs:subClassOf <MetaTestEnvironment> .

<TestEnvironmentLaboratory> a rdfs:Class ;
	rdfs:label "Test laboratory" ;
	rdfs:subClassOf <MetaTestEnvironment> .

<TestEnvironmentSimulator> a rdfs:Class ;
	rdfs:label "Simulator" ;
	rdfs:subClassOf <MetaTestEnvironment> .

<TestEnvironmentRoad> a rdfs:Class ;
	rdfs:label "Public road" ;
	rdfs:subClassOf <MetaTestEnvironment> .

<VehicleTypeTractor> a rdfs:Class ;
	rdfs:label "Tractor" ;
	rdfs:subClassOf <MetaVehicleType> .

<VehicleTypeHgv> a rdfs:Class ;
	rdfs:label "HGV" ;
	rdfs:subClassOf <MetaVehicleType> .

<VehicleTypeBus> a rdfs:Class ;
	rdfs:label "Bus" ;
	rdfs:subClassOf <MetaVehicleType> .

<VehicleTypeCar> a rdfs:Class ;
	rdfs:label "Car" ;
	rdfs:subClassOf <MetaVehicleType> .

<CertificationCEcap> a rdfs:Class ;
	rdfs:label "C-ECAP" ;
	rdfs:subClassOf <MetaCertificationStandard> .

<CertificationEuroNcap> a rdfs:Class ;
	rdfs:label "EURO-NCAP" ;
	rdfs:subClassOf <MetaCertificationStandard> .

<AdasFeatureTsr> a rdfs:Class ;
	rdfs:label "Traffic sign recognition" ;
	rdfs:subClassOf <MetaAdasFeature> .

<AdasFeatureAeb> a rdfs:Class ;
	rdfs:label "Automatic emergency braking" ;
	rdfs:subClassOf <MetaAdasFeature> .

<AdasFeatureLca> a rdfs:Class ;
	rdfs:label "Lane centering assist" ;
	rdfs:subClassOf <MetaAdasFeature> .

<AdasFeatureLdw> a rdfs:Class ;
	rdfs:label "Lane departure warning" ;
	rdfs:subClassOf <MetaAdasFeature> .

<AdasFeatureAcc> a rdfs:Class ;
	rdfs:label "Adaptive cruise control" ;
	rdfs:subClassOf <MetaAdasFeature> .

<AdasFeatureAps> a rdfs:Class ;
	rdfs:label "Automatic parking system" ;
	rdfs:subClassOf <MetaAdasFeature> .

<AdasFeatureLka> a rdfs:Class ;
	rdfs:label "Lane keep assist" ;
	rdfs:subClassOf <MetaAdasFeature> .

<AutonomyLevel5> a rdfs:Class ;
	rdfs:label "SAE level 5" ;
	rdfs:subClassOf <MetaAutonomyLevel> .

<AutonomyLevel4> a rdfs:Class ;
	rdfs:label "SAE level 4" ;
	rdfs:subClassOf <MetaAutonomyLevel> .

<AutonomyLevel3> a rdfs:Class ;
	rdfs:label "SAE level 3" ;
	rdfs:subClassOf <MetaAutonomyLevel> .

<AutonomyLevel2> a rdfs:Class ;
	rdfs:label "SAE level 2" ;
	rdfs:subClassOf <MetaAutonomyLevel> .

<AutonomyLevel1> a rdfs:Class ;
	rdfs:label "SAE level 1" ;
	rdfs:subClassOf <MetaAutonomyLevel> .

<AutonomyLevel0> a rdfs:Class ;
	rdfs:label "SAE level 0" ;
	rdfs:subClassOf <MetaAutonomyLevel> .

<SourceMachineLearning> a rdfs:Class ;
	rdfs:label "Machine learning" ;
	rdfs:subClassOf <MetaSourceType> .

<SourceHandCrafted> a rdfs:Class ;
	rdfs:label "Hand crafted" ;
	rdfs:subClassOf <MetaSourceType> .

<SourceSimulation> a rdfs:Class ;
	rdfs:label "Simulation" ;
	rdfs:subClassOf <MetaSourceType> .

<SourceRealWorld> a rdfs:Class ;
	rdfs:label "Real-world" ;
	rdfs:subClassOf <MetaSourceType> .

<HazardFatal> a rdfs:Class ;
	rdfs:label "Fatal collision" ;
	rdfs:subClassOf <MetaHazardLevel> .

<HazardMajor> a rdfs:Class ;
	rdfs:label "Major collision" ;
	rdfs:subClassOf <MetaHazardLevel> .

<HazardMinor> a rdfs:Class ;
	rdfs:label "Minor collision" ;
	rdfs:subClassOf <MetaHazardLevel> .

<HazardNearMiss> a rdfs:Class ;
	rdfs:label "Near miss" ;
	rdfs:subClassOf <MetaHazardLevel> .

<HazardNone> a rdfs:Class ;
	rdfs:label "Non-hazardous" ;
	rdfs:subClassOf <MetaHazardLevel> .

<AbstractionLevelConcrete> a rdfs:Class ;
	rdfs:label "Concrete" ;
	rdfs:subClassOf <MetaAbstractionLevel> .

<AbstractionLevelLogical> a rdfs:Class ;
	rdfs:label "Logical" ;
	rdfs:subClassOf <MetaAbstractionLevel> .

<AbstractionLevelFunctional> a rdfs:Class ;
	rdfs:label "Functional" ;
	rdfs:subClassOf <MetaAbstractionLevel> .

<LaneMarkingBottsDots> a rdfs:Class ;
	rdfs:label "Botts dots" ;
	rdfs:subClassOf asam:LaneSpecificationMarking .

<LaneMarkingDoubleSolidLine> a rdfs:Class ;
	rdfs:label "Double solid line" ;
	rdfs:subClassOf asam:LaneSpecificationMarking .

<LaneMarkingNoLine> a rdfs:Class ;
	rdfs:label "No line" ;
	rdfs:subClassOf asam:LaneSpecificationMarking .

<LaneMarkingSolidLine> a rdfs:Class ;
	rdfs:label "Solid line" ;
	rdfs:subClassOf asam:LaneSpecificationMarking .

<LaneMarkingBrokenLine> a rdfs:Class ;
	rdfs:label "Broken line" ;
	rdfs:subClassOf asam:LaneSpecificationMarking .

<V2iGlosa> a rdfs:Class ;
	rdfs:label "GLOSA" ;
	rdfs:subClassOf asam:CommunicationV2i .

<StreetFurnitureTrafficIsland> a rdfs:Class ;
	rdfs:label "Traffic island" ;
	rdfs:subClassOf asam:ScenerySpecialStructure .

<StreetFurnitureLayby> a rdfs:Class ;
	rdfs:label "Layby" ;
	rdfs:subClassOf asam:ScenerySpecialStructure .

<SpecialStructureCentralReservation> a rdfs:Class ;
	rdfs:label "Central reservation" ;
	rdfs:subClassOf asam:ScenerySpecialStructure .

<TrafficLaneSplitting> a rdfs:Class ;
	rdfs:label "Splitting lanes" ;
	rdfs:subClassOf asam:LaneTypeTraffic .

<TrafficLaneMerging> a rdfs:Class ;
	rdfs:label "Merging lanes" ;
	rdfs:subClassOf asam:LaneTypeTraffic .

<LaneTypeCarPool> a rdfs:Class ;
	rdfs:label "Car pool" ;
	rdfs:subClassOf asam:LaneSpecificationType .

<CrossroadNonSignalised> a rdfs:Class ;
	rdfs:label "Non-signalised crossroad" ;
	rdfs:subClassOf asam:IntersectionCrossroad .

<CrossroadSignalised> a rdfs:Class ;
	rdfs:label "Signalised crossroad" ;
	rdfs:subClassOf asam:IntersectionCrossroad .

<StreetFurnitureSpeedCamera> a rdfs:Class ;
	rdfs:label "Speed camera" ;
	rdfs:subClassOf asam:FixedStructureStreetFurniture .

<StreetFurnitureBusStop> a rdfs:Class ;
	rdfs:label "Bus stop" ;
	rdfs:subClassOf asam:FixedStructureStreetFurniture .

<PedestrianCrossingJunctionControlled> a rdfs:Class ;
	rdfs:label "Junction controlled crossing" ;
	rdfs:subClassOf asam:SpecialStructurePedestrianCrossing .

<PedestrianCrossingUncontrolled> a rdfs:Class ;
	rdfs:label "Uncontrolled crossing" ;
	rdfs:subClassOf asam:SpecialStructurePedestrianCrossing .

<PedestrianCrossingZebraIsland> a rdfs:Class ;
	rdfs:label "Zebra island crossing" ;
	rdfs:subClassOf asam:SpecialStructurePedestrianCrossing .

<PedestrianCrossingZebra> a rdfs:Class ;
	rdfs:label "Zebra crossing" ;
	rdfs:subClassOf asam:SpecialStructurePedestrianCrossing .

<PedestrianCrossingToucan> a rdfs:Class ;
	rdfs:label "Toucan crossing" ;
	rdfs:subClassOf asam:SpecialStructurePedestrianCrossing .

<PedestrianCrossingPuffin> a rdfs:Class ;
	rdfs:label "Puffin crossing" ;
	rdfs:subClassOf asam:SpecialStructurePedestrianCrossing .

<PedestrianCrossingPelican> a rdfs:Class ;
	rdfs:label "Pelican crossing" ;
	rdfs:subClassOf asam:SpecialStructurePedestrianCrossing .

<MetaAbstractionLevel> a rdfs:Class ;
	rdfs:label "Scenario type" ;
	rdfs:subClassOf asam:AdminTag .

<MetaHazardLevel> a rdfs:Class ;
	rdfs:label "Hazard level" ;
	rdfs:subClassOf asam:AdminTag .

<MetaSourceType> a rdfs:Class ;
	rdfs:label "Source" ;
	rdfs:subClassOf asam:AdminTag .

<MetaAutonomyLevel> a rdfs:Class ;
	rdfs:label "Autonomy level" ;
	rdfs:subClassOf asam:AdminTag .

<MetaAdasFeature> a rdfs:Class ;
	rdfs:label "ADAS feature" ;
	rdfs:subClassOf asam:AdminTag .

<MetaCertificationStandard> a rdfs:Class ;
	rdfs:label "Certification standard" ;
	rdfs:subClassOf asam:AdminTag .

<MetaVehicleType> a rdfs:Class ;
	rdfs:label "Vehicle type" ;
	rdfs:subClassOf asam:AdminTag .

<MetaTestEnvironment> a rdfs:Class ;
	rdfs:label "Test environment" ;
	rdfs:subClassOf asam:AdminTag .

<MetaAccidentCause> a rdfs:Class ;
	rdfs:label "Accident cause" ;
	rdfs:subClassOf asam:AdminTag .