Dangerous Goods Look Up by UN Number

• Overview
• Endpoint & Parameters
• Request Format
• Response Format
• Mapping to DG Content Object
• Example Implementation

Overview

This guide explains how to use the MachShip API to look up dangerous goods information by UN number. This can be useful when creating consignments with dangerous goods, as it allows you to retrieve detailed information about specific dangerous goods based on their UN numbers.

API Endpoint & Parameters

Important Note: This endpoint uses the v1 API format, which has a different URL structure than the v2 API endpoints.

The endpoint accepts one or more UN numbers as query parameters:

GET https://live.machship.com/api/DangerousGoods/GetUnNumberInformation?unNumbers=0034&unNumbers=1234

UN Number Format

UN numbers must be provided as 4-digit strings. For UN numbers less than 1000, you must pad with leading zeros:

• UN 34 → 0034
• UN 567 → 0567
• UN 1234 → 1234

You can include multiple UN numbers in a single request by repeating the unNumbers parameter.

Response Format

The response is a JSON object containing an array of dangerous goods information:

{
    "object": [
        {
            "unNumber": 34,
            "name": "BOMBS with bursting charge",
            "packingGroupName": "N/A",
            "packingGroup": 4,
            "classes": [
                {
                    "class": "1",
                    "classType": 19,
                    "division": "1D",
                    "label": "Explosives",
                    "subRisk": false
                }
            ],
            "requiresTechnicalName": false,
            "class": {
                "class": "1",
                "classType": 19,
                "division": "1D",
                "label": "Explosives",
                "subRisk": false
            },
            "subClasses": [],
            "classesForDisplay": "1.1D",
            "subClassesForDisplay": null
        },
        {
            "unNumber": 1234,
            "name": "METHYLAL",
            "packingGroupName": "II",
            "packingGroup": 2,
            "classes": [
                {
                    "class": "3",
                    "classType": 5,
                    "division": null,
                    "label": "Flammable liquids",
                    "subRisk": false
                }
            ],
            "requiresTechnicalName": false,
            "class": {
                "class": "3",
                "classType": 5,
                "division": null,
                "label": "Flammable liquids",
                "subRisk": false
            },
            "subClasses": [],
            "classesForDisplay": "3",
            "subClassesForDisplay": null
        }
    ],
    "errors": null,
    "refreshSession": false
}

Mapping to DG Content Object

When creating a dangerous goods consignment, you need to map the response from this endpoint to the consignmentItemDgItems object. It's important to use the enum values rather than the descriptive values.

Here's how to map the key fields:

Example Mapping

For the UN 1234 (METHYLAL) example above, the mapping would be:

{
  "consignmentItemDgItems": [
    {
      "unNumber": 1234,
      "packingGroup": 2,
      "dgClassType": 5,
      "subDgClassTypes": [],
      // Other required fields would be added here
      "containerType": 1,
      "aggregateQuantity": 20,
      "isAggregateQuantityWeight": false,
      "numberOfContainers": 1,
      "isMarinePollutant": false,
      "isTemperatureControlled": false
    }
  ]
}

Remember to include all required fields for your consignment and to handle errors appropriately in your implementation.