feat(geocoding): implement address search and reverse geocoding APIs

server/api/geocoding/reverse.get.ts

@@ -0,0 +1,19 @@
+import { createError, getQuery } from 'h3'
+import { reverseGeocode } from '../../utils/geocoding'
+
+export default defineEventHandler(async (event) => {
+  const query = getQuery(event)
+  const latitude = typeof query.lat === 'string' ? Number.parseFloat(query.lat) : Number.NaN
+  const longitude = typeof query.lng === 'string' ? Number.parseFloat(query.lng) : Number.NaN
+
+  if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Invalid coordinates'
+    })
+  }
+
+  const address = await reverseGeocode(latitude, longitude)
+
+  return { address }
+})

server/api/geocoding/search.get.ts

@@ -0,0 +1,20 @@
+import { createError, getQuery } from 'h3'
+import { searchAddresses } from '../../utils/geocoding'
+
+export default defineEventHandler(async (event) => {
+  const query = getQuery(event)
+  const rawText = typeof query.q === 'string' ? query.q.trim() : ''
+  const rawLimit = typeof query.limit === 'string' ? Number.parseInt(query.limit, 10) : 5
+  const limit = Number.isFinite(rawLimit) ? Math.min(Math.max(rawLimit, 1), 8) : 5
+
+  if (rawText.length < 3) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Query too short'
+    })
+  }
+
+  const suggestions = await searchAddresses(rawText, limit)
+
+  return { suggestions }
+})

server/utils/geocoding.ts

@@ -0,0 +1,123 @@
+interface NominatimAddress {
+  road?: string
+  house_number?: string
+  pedestrian?: string
+  footway?: string
+  path?: string
+  cycleway?: string
+  suburb?: string
+  neighbourhood?: string
+  city?: string
+  town?: string
+  village?: string
+  municipality?: string
+}
+
+interface NominatimResult {
+  lat: string
+  lon: string
+  display_name: string
+  address?: NominatimAddress
+}
+
+export interface GeocodingSuggestion {
+  label: string
+  latitude: number
+  longitude: number
+}
+
+const NOMINATIM_BASE_URL = 'https://nominatim.openstreetmap.org'
+const BARI_BOUNDS = {
+  north: 41.1696,
+  south: 41.0718,
+  east: 16.9521,
+  west: 16.7564
+}
+
+const NOMINATIM_HEADERS = {
+  'User-Agent': 'Visione Frontend/1.0 (https://visione.studentindipendenti.it)',
+  'Referer': 'https://visione.studentindipendenti.it/'
+}
+
+const bariViewbox = `${BARI_BOUNDS.west},${BARI_BOUNDS.north},${BARI_BOUNDS.east},${BARI_BOUNDS.south}`
+
+const isWithinBariBounds = (latitude: number, longitude: number) =>
+  latitude >= BARI_BOUNDS.south &&
+  latitude <= BARI_BOUNDS.north &&
+  longitude >= BARI_BOUNDS.west &&
+  longitude <= BARI_BOUNDS.east
+
+const compactAddress = (displayName: string, address?: NominatimAddress) => {
+  if (!address) {
+    return displayName
+  }
+
+  const streetName = address.road || address.pedestrian || address.footway || address.path || address.cycleway
+  const street = [streetName, address.house_number].filter(Boolean).join(' ')
+  const locality = address.city || address.town || address.village || address.municipality || 'Bari'
+  const area = address.suburb || address.neighbourhood
+  const formatted = [street, locality, area]
+    .filter(Boolean)
+    .filter((part, index, all) => all.indexOf(part) === index)
+    .join(', ')
+
+  return formatted || displayName
+}
+
+const toSuggestion = (result: NominatimResult): GeocodingSuggestion | null => {
+  const latitude = Number.parseFloat(result.lat)
+  const longitude = Number.parseFloat(result.lon)
+
+  if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) {
+    return null
+  }
+
+  return {
+    label: compactAddress(result.display_name, result.address),
+    latitude,
+    longitude
+  }
+}
+
+export const searchAddresses = async (query: string, limit = 5) => {
+  const params = new URLSearchParams({
+    q: query,
+    format: 'jsonv2',
+    addressdetails: '1',
+    'accept-language': 'it',
+    countrycodes: 'it',
+    bounded: '1',
+    viewbox: bariViewbox,
+    limit: String(limit)
+  })
+
+  const results = await $fetch<NominatimResult[]>(`${NOMINATIM_BASE_URL}/search?${params.toString()}`, {
+    headers: NOMINATIM_HEADERS
+  })
+
+  return results
+    .map(toSuggestion)
+    .filter((result): result is GeocodingSuggestion => Boolean(result))
+    .filter((result) => isWithinBariBounds(result.latitude, result.longitude))
+}
+
+export const reverseGeocode = async (latitude: number, longitude: number) => {
+  const params = new URLSearchParams({
+    lat: String(latitude),
+    lon: String(longitude),
+    zoom: '18',
+    format: 'jsonv2',
+    addressdetails: '1',
+    'accept-language': 'it'
+  })
+
+  const result = await $fetch<NominatimResult | null>(`${NOMINATIM_BASE_URL}/reverse?${params.toString()}`, {
+    headers: NOMINATIM_HEADERS
+  })
+
+  if (!result) {
+    return ''
+  }
+
+  return compactAddress(result.display_name, result.address)
+}