feat: add GET /api/stations nearby stations endpoint with haversine query and search logging

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app/Http/Controllers/Api/StationController.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace App\Http\Controllers\Api;
+
+use App\Http\Controllers\Controller;
+use App\Http\Requests\Api\NearbyStationsRequest;
+use App\Http\Resources\Api\StationResource;
+use App\Models\Search;
+use App\Models\Station;
+use Illuminate\Database\Query\JoinClause;
+use Illuminate\Http\JsonResponse;
+
+class StationController extends Controller
+{
+    public function index(NearbyStationsRequest $request): JsonResponse
+    {
+        $lat = (float) $request->input('lat');
+        $lng = (float) $request->input('lng');
+        $fuelType = $request->fuelType();
+        $radius = $request->radius();
+        $sort = $request->sort();
+
+        $all = Station::query()
+            ->selectRaw(
+                'stations.*, spc.price_pence, spc.fuel_type, spc.price_effective_at,
+                (6371 * acos(MAX(-1.0, MIN(1.0,
+                    cos(radians(?)) * cos(radians(lat)) * cos(radians(lng) - radians(?))
+                    + sin(radians(?)) * sin(radians(lat))
+                )))) AS distance_km',
+                [$lat, $lng, $lat],
+            )
+            ->join('station_prices_current as spc', function (JoinClause $join) use ($fuelType): void {
+                $join->on('stations.node_id', '=', 'spc.station_id')
+                    ->where('spc.fuel_type', '=', $fuelType->value);
+            })
+            ->where('stations.temporary_closure', false)
+            ->where('stations.permanent_closure', false)
+            ->get();
+
+        $stations = $all
+            ->filter(fn ($s) => (float) $s->distance_km <= $radius)
+            ->sortBy($sort === 'price' ? 'price_pence' : 'distance_km')
+            ->values();
+
+        $prices = $stations->pluck('price_pence');
+
+        Search::create([
+            'lat_bucket' => round($lat, 2),
+            'lng_bucket' => round($lng, 2),
+            'fuel_type' => $fuelType->value,
+            'results_count' => $stations->count(),
+            'lowest_pence' => $prices->min(),
+            'highest_pence' => $prices->max(),
+            'avg_pence' => $prices->isNotEmpty() ? round($prices->avg(), 2) : null,
+            'searched_at' => now(),
+            'ip_hash' => hash('sha256', $request->ip() ?? ''),
+        ]);
+
+        return response()->json([
+            'data' => StationResource::collection($stations),
+            'meta' => [
+                'count' => $stations->count(),
+                'fuel_type' => $fuelType->value,
+                'radius_km' => $radius,
+                'lowest_pence' => $prices->min(),
+                'highest_pence' => $prices->max(),
+                'cheapest_price_pence' => $prices->min(),
+                'avg_pence' => $prices->isNotEmpty() ? round($prices->avg(), 2) : null,
+            ],
+        ]);
+    }
+}

app/Http/Requests/Api/NearbyStationsRequest.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Http\Requests\Api;
+
+use App\Enums\FuelType;
+use Illuminate\Foundation\Http\FormRequest;
+
+class NearbyStationsRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            'lat' => ['required', 'numeric', 'between:-90,90'],
+            'lng' => ['required', 'numeric', 'between:-180,180'],
+            'fuel_type' => ['required', 'string'],
+            'radius' => ['nullable', 'numeric', 'between:0.1,50'],
+            'sort' => ['nullable', 'string', 'in:price,distance'],
+            'pricing_mode' => ['nullable', 'string', 'in:pump'],
+        ];
+    }
+
+    public function fuelType(): FuelType
+    {
+        return FuelType::fromAlias($this->string('fuel_type')->toString());
+    }
+
+    public function radius(): float
+    {
+        return (float) $this->input('radius', 10.0);
+    }
+
+    public function sort(): string
+    {
+        return $this->input('sort', 'price');
+    }
+}

app/Http/Resources/Api/StationResource.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace App\Http\Resources\Api;
+
+use Illuminate\Http\Request;
+use Illuminate\Http\Resources\Json\JsonResource;
+use Illuminate\Support\Carbon;
+
+class StationResource extends JsonResource
+{
+    public function toArray(Request $request): array
+    {
+        return [
+            'station_id' => $this->node_id,
+            'name' => $this->trading_name,
+            'brand' => $this->brand_name,
+            'is_supermarket' => (bool) $this->is_supermarket,
+            'address' => implode(', ', array_filter([$this->address_line_1, $this->city])),
+            'postcode' => $this->postcode,
+            'lat' => (float) $this->lat,
+            'lng' => (float) $this->lng,
+            'distance_km' => round((float) $this->distance_km, 2),
+            'fuel_type' => $this->fuel_type,
+            'price_pence' => (int) $this->price_pence,
+            'price' => round((int) $this->price_pence / 100, 2),
+            'price_updated_at' => $this->price_effective_at
+                ? Carbon::parse($this->price_effective_at)->toISOString()
+                : null,
+        ];
+    }
+}