Merge pull request #9 from amattu2/feat/additional-endpoints

feat: Support `GetModelsForMakeYear` and `GetModelsForMake`

Author: amattu2

README.md

@@ -43,7 +43,7 @@ $decode = amattu2\NHTSA\Client::decodeVIN("VIN_NUMBER");
 
 Success return result
 
-```
+```txt
 Array
 (
   [Error Text] =>
@@ -125,7 +125,7 @@ $recalls = amattu2\NHTSA\Client::getRecalls(2015, "Ford", "Mustang");
 
 Success return result
 
-```
+```txt
 Array
 (
   [0] => Array
@@ -171,7 +171,7 @@ $pretty_recalls = amattu2\NHTSA\Client::parseRecalls($recalls);
 
 Success return result
 
-```
+```txt
 Array
 (
   [2] => Array
@@ -191,6 +191,146 @@ Array
 )
 ```
 
+## getModelsForMakeByYear
+
+PHPDoc
+
+```PHP
+/**
+ * Get all available models for a make by year
+ *
+ * @note This is a free-text match. Recommend using `getModelsForMakeIdByYear`
+ * @param int $year The model year
+ * @param string $make The make
+ */
+```
+
+Usage
+
+```PHP
+$models = amattu2\NHTSA\Client::getModelsForMakeByYear(2015, "Ford");
+```
+
+Success return result
+
+```txt
+Array
+(
+  [0] => Array
+  (
+    [Make_ID] => 441
+    [Make_Name] => FORD
+    [Model_ID] => 2021
+    [Model_Name] => C-MAX
+  )
+  ...
+)
+```
+
+## getModelsForMakeIdByYear
+
+PHPDoc
+
+```PHP
+/**
+ * Get all available models for a make by year
+ *
+ * @param int $year The model year
+ * @param int $make_id The make ID
+ */
+```
+
+Usage
+
+```PHP
+$models = amattu2\NHTSA\Client::getModelsForMakeIdByYear(2015, 441);
+```
+
+Success return result
+
+```txt
+Array
+(
+  [0] => Array
+  (
+    [Make_ID] => 441
+    [Make_Name] => FORD
+    [Model_ID] => 2021
+    [Model_Name] => C-MAX
+  )
+  ...
+)
+```
+
+## getModelsForMake
+
+PHPDoc
+
+```PHP
+/**
+ * Get all available models for a make
+ *
+ * @param string $make The make
+ */
+```
+
+Usage
+
+```PHP
+$models = amattu2\NHTSA\Client::getModelsForMake("Ford");
+```
+
+Success return result
+
+```txt
+Array
+(
+  [0] => Array
+  (
+    [Make_ID] => 441
+    [Make_Name] => FORD
+    [Model_ID] => 2021
+    [Model_Name] => C-MAX
+  )
+  ...
+)
+```
+
+## getModelsForMakeId
+
+PHPDoc
+
+```PHP
+/**
+ * Get all available models for a make
+ *
+ * @param int $make_id The make ID
+ */
+```
+
+Usage
+
+```PHP
+$models = amattu2\NHTSA\Client::getModelsForMakeId(441);
+```
+
+Success return result
+
+```txt
+Array
+(
+  [0] => Array
+  (
+    [Make_ID] => 441
+    [Make_Name] => FORD
+    [Model_ID] => 2021
+    [Model_Name] => C-MAX
+  )
+  ...
+)
+```
+
 # Requirements & Dependencies
 
-PHP 7.0 +
+- PHP 7.4+
+- cURL Extension

composer.json

@@ -14,5 +14,8 @@
             "email": "alecmattu1234@gmail.com"
         }
     ],
-    "require": {}
+    "require": {
+        "php": ">=7.4",
+        "ext-curl": "*"
+    }
 }

composer.lock

@@ -20,12 +20,11 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
-
 // Files
 require "vendor/autoload.php";
 
 // Optional VIN $_GET input
-$vin = isset($_GET['vin']) && !empty($_GET['vin']) ? $_GET['vin'] : "2B3KA43R86H389824";
+// $vin = isset($_GET['vin']) && !empty($_GET['vin']) ? $_GET['vin'] : "2B3KA43R86H389824";
 
 // Perform raw decode
 // echo "<h1>Perform raw decode</h1>", "<pre>";
@@ -48,3 +47,27 @@
 // echo "<h1>Pretty parse raw recall request</h1>", "<pre>";
 // print_r(amattu2\NHTSA\Client::parseRecalls($recalls));
 // echo "</pre>";
+
+// getModelsForMakeByYear
+
+// echo "<h1>Get models for make by year</h1>", "<pre>";
+// print_r(amattu2\NHTSA\Client::getModelsForMakeByYear(2015, "Ford));
+// echo "</pre>";
+
+// getModelsForMakeIdByYear
+
+// echo "<h1>Get models for make by year</h1>", "<pre>";
+// print_r(amattu2\NHTSA\Client::getModelsForMakeIdByYear(2015, 460));
+// echo "</pre>";
+
+// getModelsForMake
+
+// echo "<h1>Get models for make</h1>", "<pre>";
+// print_r(amattu2\NHTSA\Client::getModelsForMake(make: "Tesla"));
+// echo "</pre>";
+
+// getModelsForMakeId
+
+// echo "<h1>Get models for make ID</h1>", "<pre>";
+// print_r(amattu2\NHTSA\Client::getModelsForMakeId(441));
+// echo "</pre>";

index.php

@@ -33,7 +33,12 @@ class Client
   private static $endpoints = [
     "decode" => "https://vpic.nhtsa.dot.gov/api/vehicles/decodevin/%s?format=json",
     "recalls" => "https://api.nhtsa.gov/recalls/recallsByVehicle?modelYear=%d&make=%s&model=%s",
+    "GetModelsForMakeYear" => "https://vpic.nhtsa.dot.gov/api/vehicles/getmodelsformakeyear/make/%s/modelyear/%d?format=json",
+    "GetModelsForMakeIdYear" => "https://vpic.nhtsa.dot.gov/api/vehicles/GetModelsForMakeIdYear/makeId/%d/modelyear/%d?format=json",
+    "GetModelsForMake" => "https://vpic.nhtsa.dot.gov/api/vehicles/GetModelsForMake/%s?format=json",
+    "GetModelsForMakeId" => "https://vpic.nhtsa.dot.gov/api/vehicles/GetModelsForMakeId/%d?format=json",
   ];
+
   private static $minimum_year = 1950;
   private static $minimum_make_length = 3;
   private static $minimum_model_length = 3;
@@ -228,6 +233,88 @@ public static function parseRecalls(array $recalls = []): ?array
     return $parsed_result;
   }
 
+  /**
+   * Get all available models for a make by year
+   *
+   * @note This is a free-text match. Recommend using `getModelsForMakeIdByYear`
+   * @param int $year The model year
+   * @param string $make The make
+   */
+  public static function getModelsForMakeByYear(int $year, string $make): ?array
+  {
+    if (!$year || $year < self::$minimum_year) {
+      return null;
+    }
+    if (!$make || strlen($make) < self::$minimum_make_length) {
+      return null;
+    }
+
+    // Fetch Data
+    $endpoint = sprintf(self::$endpoints["GetModelsForMakeYear"], rawurlencode(strtoupper($make)), $year);
+    $result = json_decode(self::http_get($endpoint), true);
+
+    return $result && isset($result["Count"]) && $result["Count"] > 0 ? $result["Results"] : null;
+  }
+
+  /**
+   * Get all available models for a make Id by year
+   *
+   * @param int $year The model year
+   * @param int $make_id The make id
+   */
+  public static function getModelsForMakeIdByYear(int $year, int $make_id): ?array
+  {
+    if (!$make_id) {
+      return null;
+    }
+    if (!$year || $year < self::$minimum_year) {
+      return null;
+    }
+
+    // Fetch Data
+    $endpoint = sprintf(self::$endpoints["GetModelsForMakeIdYear"], $make_id, $year);
+    $result = json_decode(self::http_get($endpoint), true);
+
+    return $result && isset($result["Count"]) && $result["Count"] > 0 ? $result["Results"] : null;
+  }
+
+  /**
+   * Get all available models for a make
+   *
+   * @note This is a free-text match. Recommend using `getModelsForMakeId`
+   * @param string $make
+   */
+  public static function GetModelsForMake(string $make): ?array
+  {
+    if (!$make || strlen($make) < self::$minimum_make_length) {
+      return null;
+    }
+
+    // Fetch Data
+    $endpoint = sprintf(self::$endpoints["GetModelsForMake"], rawurlencode(strtoupper($make)));
+    $result = json_decode(self::http_get($endpoint), true);
+
+    return $result && isset($result["Count"]) && $result["Count"] > 0 ? $result["Results"] : null;
+  }
+
+  /**
+   * Get all available models for a make Id
+   *
+   * @param int $make_id The make id
+   */
+  public static function GetModelsForMakeId(int $make_id): ?array
+  {
+    if (!$make_id) {
+      return null;
+    }
+
+    // Fetch Data
+    $endpoint = sprintf(self::$endpoints["GetModelsForMakeId"], $make_id);
+    $result = json_decode(self::http_get($endpoint), true);
+
+    return $result && isset($result["Count"]) && $result["Count"] > 0 ? $result["Results"] : null;
+  }
+
   /**
    * Parse Unix Timestamp (Miliseconds with offset)
    *