feat: add postal code detection endpoint

Author: sooluh

README.md

@@ -63,28 +63,47 @@ The fastest way to use it privately on PaaS available
   <img alt="Deploy with Render" src="https://render.com/images/deploy-to-render-button.svg" height="32" />
 </a>
 
-## Basic Usage
+## Endpoints
+
+### Search by Place Name
 
 ```
 [ENDPOINT] /search
 ```
 
 <pre>
-[GET] <a href="https://kodepos.vercel.app/?q=danasari">http://localhost:3000/search/?q=danasari</a>
+[GET] <a href="https://kodepos.vercel.app/search/?q=danasari">http://localhost:3000/search/?q=danasari</a>
+</pre>
+
+#### Query strings
+
+| Params | Description | Required |
+| ------ | ----------- | :------: |
+| q      | keywords    |   [x]    |
+
+### Search by Coordinates
+
+```
+[ENDPOINT] /detect
+```
+
+<pre>
+[GET] <a href="https://kodepos.vercel.app/detect/?latitude=-6.547052&longitude=107.3980201">http://localhost:3000/detect/?latitude=-6.547052&longitude=107.3980201</a>
 </pre>
 
 #### Query strings
 
-| params | description | required |
-| ------ | :---------: | :------: |
-| q      |  keywords   |  `true`  |
+| Params    | Description | Required |
+| --------- | ----------- | :------: |
+| latitude  | -           |   [x]    |
+| longitude | -           |   [x]    |
 
-### Example of Use
+### Basic Usage
 
 #### Request
 
 <pre>
-curl -XGET '<a href="https://kodepos.vercel.app/?q=danasari">http://localhost:3000/search/?q=danasari</a>'
+curl -XGET '<a href="https://kodepos.vercel.app/search/?q=danasari">http://localhost:3000/search/?q=danasari</a>'
 </pre>
 
 #### Response
@@ -159,8 +178,8 @@ List of server APIs ready to use publicly
 > [!IMPORTANT]
 > For production usage, we recommend deploying it on your own and not using the list below. The list below can be used for development or learning purposes only!
 
-- [https://kodepos.vercel.app](https://kodepos.vercel.app/?q=danasari) `latest`
-- [https://kodepos.onrender.com](https://kodepos.onrender.com/?q=danasari) `latest`
+- [https://kodepos.vercel.app](https://kodepos.vercel.app/search/?q=danasari) `latest`
+- [https://kodepos.onrender.com](https://kodepos.onrender.com/search/?q=danasari) `latest`
 
 ### License
 

app/controllers/detect.ts

@@ -0,0 +1,25 @@
+import { DetectQueries } from '../../types'
+import { nearestDetection } from '../helpers/kodepos'
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
+import { createSpecResponse, sendBadRequest, sendNotFound } from '../helpers/spec'
+
+export const detect = (app: FastifyInstance) => {
+  return async (request: FastifyRequest<{ Querystring: DetectQueries }>, reply: FastifyReply) => {
+    const { latitude, longitude } = request.query
+
+    if (!latitude || !longitude) {
+      return sendBadRequest(reply, "The 'latitude' and 'longitude' parameters is required.")
+    }
+
+    const result = nearestDetection(app.data, latitude, longitude)
+
+    if (!result) {
+      return sendNotFound(reply)
+    }
+
+    const response = createSpecResponse(result)
+
+    reply.header('Cache-Control', 's-maxage=86400, stale-while-revalidate=604800')
+    return reply.send(response)
+  }
+}

app/controllers/home.ts

@@ -1,9 +1,9 @@
 import qs from 'node:querystring'
-import { KeywordOptions } from '../../types'
+import { SearchQueries } from '../../types'
 import type { FastifyReply, FastifyRequest } from 'fastify'
 
 export const home = async (
-  request: FastifyRequest<{ Querystring: KeywordOptions }>,
+  request: FastifyRequest<{ Querystring: SearchQueries }>,
   reply: FastifyReply
 ) => {
   const { q } = request.query

app/controllers/search.ts

@@ -1,14 +1,14 @@
-import { KeywordOptions } from '../../types'
+import { SearchQueries } from '../../types'
 import { createSpecResponse, sendBadRequest } from '../helpers/spec'
 import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
 
 export const search = (app: FastifyInstance) => {
-  return async (request: FastifyRequest<{ Querystring: KeywordOptions }>, reply: FastifyReply) => {
+  return async (request: FastifyRequest<{ Querystring: SearchQueries }>, reply: FastifyReply) => {
     const { q } = request.query
     // TODO: search by province, regency, or district
 
     if (!q) {
-      return sendBadRequest(reply)
+      return sendBadRequest(reply, "The 'q' parameter is required.")
     }
 
     const keywords = q

app/helpers/kodepos.ts

@@ -0,0 +1,52 @@
+import { DataResult } from '../../types'
+
+export const createFullText = (data: DataResult) => {
+  const keys = ['code', 'village', 'district', 'regency', 'province']
+  const combinations: string[] = []
+
+  keys.forEach((a, x) => {
+    keys.forEach((b, y) => {
+      if (x !== y) {
+        combinations.push(`${data[a]} ${data[b]}`)
+      }
+    })
+  })
+
+  return combinations.join(' ')
+}
+
+export const haversineDistance = (lat1: number, lon1: number, lat2: number, lon2: number) => {
+  const R = 6371 // earth radius in km
+  const dLat = ((lat2 - lat1) * Math.PI) / 180
+  const dLon = ((lon2 - lon1) * Math.PI) / 180
+  const a =
+    Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+    Math.cos((lat1 * Math.PI) / 180) *
+      Math.cos((lat2 * Math.PI) / 180) *
+      Math.sin(dLon / 2) *
+      Math.sin(dLon / 2)
+  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
+
+  return R * c // distance in km
+}
+
+export const nearestDetection = (
+  data: DataResult[],
+  lat: number,
+  lon: number
+): DataResult | null => {
+  let nearest: DataResult | null = null
+  let smallestDistance = Infinity
+
+  data.forEach((item) => {
+    const distance = haversineDistance(lat, lon, item.latitude, item.longitude)
+
+    if (distance < smallestDistance) {
+      nearest = item
+      smallestDistance = distance
+      nearest.distance = distance
+    }
+  })
+
+  return nearest
+}

app/helpers/spec.ts

@@ -22,10 +22,10 @@ export const sendNotFound = (reply: FastifyReply) => {
   })
 }
 
-export const sendBadRequest = (reply: FastifyReply) => {
+export const sendBadRequest = (reply: FastifyReply, message?: string) => {
   return reply.status(400).send({
     statusCode: 400,
     code: 'BAD_REQUEST',
-    message: "The 'q' parameter must be filled.",
+    message: message || "The request body doesn't contain valid data.",
   })
 }

start/core.ts

@@ -3,23 +3,9 @@ import * as path from 'path'
 import { routes } from './routes'
 import * as fs from 'node:fs/promises'
 import type { DataResult } from '../types'
+import { createFullText } from '../app/helpers/kodepos'
 import type { FastifyInstance, FastifyPluginOptions } from 'fastify'
 
-const createFullText = (data: DataResult) => {
-  const keys = ['code', 'village', 'district', 'regency', 'province']
-  const combinations: string[] = []
-
-  keys.forEach((a, x) => {
-    keys.forEach((b, y) => {
-      if (x !== y) {
-        combinations.push(`${data[a]} ${data[b]}`)
-      }
-    })
-  })
-
-  return combinations.join(' ')
-}
-
 const load = async (app: FastifyInstance, _: FastifyPluginOptions) => {
   const text = await fs.readFile(path.resolve('data/kodepos.json'), { encoding: 'utf-8' })
   const json: DataResult[] = JSON.parse(text)
@@ -35,6 +21,8 @@ const load = async (app: FastifyInstance, _: FastifyPluginOptions) => {
   })
 
   app.decorate('fuse', fuse)
+  app.decorate('data', json)
+
   routes(app)
 }
 

start/routes.ts

@@ -1,8 +1,10 @@
 import { home } from '../app/controllers/home'
 import type { FastifyInstance } from 'fastify'
+import { detect } from '../app/controllers/detect'
 import { search } from '../app/controllers/search'
 
 export const routes = (app: FastifyInstance) => {
   app.get('/', home)
   app.get('/search', search(app))
+  app.get('/detect', detect(app))
 }

types/fastify/index.d.ts

@@ -4,5 +4,6 @@ import { DataResult } from '..'
 declare module 'fastify' {
   export interface FastifyInstance {
     fuse: Fuse<DataResult>
+    data: DataResult[]
   }
 }

types/index.ts

@@ -1,10 +1,15 @@
-export type KeywordOptions = {
+export type SearchQueries = {
   q: string
   province?: string
   regency?: string
   district?: string
 }
 
+export type DetectQueries = {
+  latitude: number
+  longitude: number
+}
+
 export type DataResult = {
   province: string
   regency: string
@@ -16,4 +21,5 @@ export type DataResult = {
   elevation: number
   timezone: string
   fulltext?: string
+  distance?: number
 }