How to Use Our APIs : HeavyEquipmentData.com

These instructions will show you how to access our equipment APIs using PHP. PHP is not required however. Any language than can make a POST request should suffice. Use the links to jump to the relevant section.

Making a spec request

Making a manufacturer naming request

Making a category naming request

Making a model naming request

To make a spec request [ POST - /api/get/specs ]

To request specs from the API, a POST request must be send to the API end-point with some required data. You must supply your API Key, the Category, Manufacturer, and the Model you are requesting specs for, and we also ask for the User-Agent of the browser making the request, along with your referring website / web page.

The following is how you would make a POST request using CURL in PHP.

// Create a data array.

$data = array(
    "apikey" => "API_KEY",
    "category" => "MACHINE_CATEGORY",
    "manufacturer" => "MACHINE_MANUFACTURER",
    "model" => "MACHINE_MODEL"
);

$params = http_build_query($data, "", "&");

// Initialize a CURL session.

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://www.heavyequipmentdata.com/api/get/specs/");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
curl_setopt($ch, CURLOPT_USERAGENT, $_SERVER['HTTP_USER_AGENT'] ?? null);
curl_setopt($ch, CURLOPT_REFERER, "YOURWEBSITE.com");
$result = curl_exec($ch);
$errors = curl_error($ch);
curl_close($ch);

// The result as an Object.
$specs = json_decode($result);

// The result as an Array.
$specs = json_decode($result, true);

The response from the API will look like this. If there was a successful match in the API, the success key will have a value of 1. Checking that key will let you know if you have any data to display. The rest of the response will be some data to acknowledge the request, and an array of specs, each containing a category, subcategory, and value keys.


{
  "success": 1,
  "apikey" => "API_KEY",
  "company": "your-company-name",
  "responseID": "6579f22e047ce",
  "response_time": "11.88 ms",
  "request": {
    "requestedCategory": "dozer",
    "requestedManufacturer": "cat",
    "requestedModel": "963",
    "useragent": "RapidAPI\/4.2.0 (Macintosh; OS X\/13.3.1) GCDHTTPRequest",
    "site": "YOURWEBSITE.com"
  },
  "specs": [
    {
      "category": "Dimensions",
      "subcategory": "Clearance at Full Height and Dump",
      "value": "10.3"
    },
    {
      "category": "Dimensions",
      "subcategory": "Ground Clearance",
      "value": "1.5"
    },
    {
      "category": "Dimensions",
      "subcategory": "Height - Top of Cab",
      "value": "10.9"
    },
    {
      "category": "Dimensions",
      "subcategory": "Length to Front of Track",
      "value": "14.4"
    },
    {
      "category": "Dimensions",
      "subcategory": "Length with Bucket on Ground",
      "value": "20.9"
    }
  ]
}

To make a manufacturer name normalization request [ POST - /api/normalize/manufacturers ]

To naming normalization from the API, a POST request must be send to the API end-point with some required data. Here, you must supply your API Key, and the name of the Manufacturer you are requesting naming normalization for, and we also ask for the User-Agent of the browser making the request, along with your referring website / web page.

The following is how you would make a POST request using CURL in PHP.

// Create a data array.
$data = array(
    "apikey" => "API_KEY",
    "manufacturer" => "MANUFACTURER_NAME",
);

$params = http_build_query($data, "", "&");

// Initialize a CURL session.

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://www.heavyequipmentdata.com/api/normalize/manufacturers");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
curl_setopt($ch, CURLOPT_USERAGENT, $_SERVER['HTTP_USER_AGENT'] ?? null);
curl_setopt($ch, CURLOPT_REFERER, "YOURWEBSITE.com");
$result = curl_exec($ch);
$errors = curl_error($ch);
curl_close($ch);

// The result as an Object.
$specs = json_decode($result);

// The result as an Array.
$specs = json_decode($result, true);

{
  "success": 1,
  "apikey" => "API_KEY",
  "company": "your-company-name",
  "responseID": "6579f1d665d35",
  "response_time": "10.76 ms",
  "request": {
    "requestedManufacturer": "cat",
    "site": "YOURWEBSITE.com"
  },
  "response-data": {
    "manufacturerName": "Caterpillar"
  }
}

A failed response will look something like this.

{
  "success": 0,
  "apikey" => "API_KEY",
  "company": "your-company-name",
  "responseID": "658c7d8822b86",
  "response_time": "10.76 ms",
  "request": {
    "site": "YOURWEBSITE.com"
  },
  "requestedManufacturer": "An Unknown Manufacturer",
  "error_message": "No manufacturer found with this name."
}

To make a Category normalization request [ POST - /api/normalize/categories ]

To request naming normalization from the API, a POST request must be send to the API end-point with some required data. Here, you must supply your API Key, and the name of the Category you are requesting naming normalization for, and we also ask for the User-Agent of the browser making the request, along with your referring website / web page.

The following is how you would make a POST request using CURL in PHP.

// Create a data array.
$data = array(
   "apikey" => "API_KEY",
   "category" => "CATEGORY_NAME",
);

$params = http_build_query($data, "", "&");

// Initialize a CURL session.

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://www.heavyequipmentdata.com/api/normalize/categories");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
curl_setopt($ch, CURLOPT_USERAGENT, $_SERVER['HTTP_USER_AGENT'] ?? null);
curl_setopt($ch, CURLOPT_REFERER, "YOURWEBSITE.com");
$result = curl_exec($ch);
$errors = curl_error($ch);
curl_close($ch);

// The result as an Object.
$specs = json_decode($result);

// The result as an Array.
$specs = json_decode($result, true);

{
  "success": 1,
  "apikey" => "API_KEY",
  "company": "your-company-name",
  "responseID": "6579f1d665d35",
  "response_time": "10.76 ms",
  "request": {
    "requestedCategory": "backhoe",
    "site": "YOURWEBSITE.com"
  },
  "response-data": {
    "categoryName": "Backhoe Loaders"
  }
}

A failed response will look something like this.

{
  "success": 0,
  "apikey" => "API_KEY",
  "company": "your-company-name",
  "responseID": "658c7d8822b86",
  "response_time": "10.76 ms",
  "request": {
    "site": "YOURWEBSITE.com"
  },
  "requestedCategory": "An Unknown Category",
  "error_message": "No category found with this name."
}

To make a Model Name normalization request [ POST - /api/normalize/models ]

To request naming normalization from the API, a POST request must be send to the API end-point with some required data. You must supply your API Key, the Category, Manufacturer, and the Model you are requesting naming normalization for, and we also ask for the User-Agent of the browser making the request, along with your referring website / web page.

The following is how you would make a POST request using CURL in PHP.

// Create a data array.
$data = array(
   "apikey" => "API_KEY",
   "category" => "CATEGORY_NAME",
   "manufacturer" => "MANUFACTURER_NAME",
   "model" => "MODEL_NAME",
);

$params = http_build_query($data, "", "&");

// Initialize a CURL session.

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://www.heavyequipmentdata.com/api/normalize/models");
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE);
curl_setopt($ch, CURLOPT_USERAGENT, $_SERVER['HTTP_USER_AGENT'] ?? null);
curl_setopt($ch, CURLOPT_REFERER, "YOURWEBSITE.com");
$result = curl_exec($ch);
$errors = curl_error($ch);
curl_close($ch);

// The result as an Object.
$specs = json_decode($result);

// The result as an Array.
$specs = json_decode($result, true);

{
  "success": 1,
  "apikey" => "API_KEY",
  "company": "your-company-name",
  "responseID": "658c807a1e882",
  "response_time": "10.76 ms",
  "request": {
    "requestedCategory": "backhoe",
    "requestedManufacturer": "cat",
    "requestedModel": "416 bn pk",
    "site": "YOURWEBSITE.com"
  },
  "respoonse-data": {
    "model": "416",
    "man": "Caterpillar",
    "cat": "Backhoe Loaders"
  }
}

A failed response will look something like this.

{
  "success": 0,
  "apikey" => "API_KEY",
  "company": "your-company-name",
  "responseID": "658c814cdc6e6",
  "response_time": "10.76 ms",
  "request": {
    "requestedCategory": "backhoe",
    "requestedManufacturer": "cat",
    "requestedModel": "416 unknown model",
    "site": "YOURWEBSITE.com"
  },
  "error_message": "This is not a model in our database."
}

API Docs

Instructions on how to connect to, and use, our heavy equipment data specification and normalization APIs.

To make a spec request [ POST - /api/get/specs ]

To make a manufacturer name normalization request [ POST - /api/normalize/manufacturers ]

To make a Category normalization request [ POST - /api/normalize/categories ]

To make a Model Name normalization request [ POST - /api/normalize/models ]