API with NestJS #183. Distance and radius in PostgreSQL with Drizzle ORM

January 13, 2025

This entry is part 183 of 186 in the API with NestJS

PostgreSQL provides many options for working with geographical data, especially with the PostGIS extension. In this article, we’ll explore how to calculate the distance between two coordinates and how to identify locations within a specific radius.

If you want to check out the basics of storing coordinates in PostgreSQL with the Drizzle ORM, check out API with NestJS #182. Storing coordinates in PostgreSQL with Drizzle ORM

Spatial Reference System Identifier

We will use a straightforward database schema that contains a table with locations.

database-schema.ts

import { serial, text, pgTable, geometry } from 'drizzle-orm/pg-core';

export const locations = pgTable('locations', {

id: serial().primaryKey(),

name: text().notNull(),

coordinates: geometry('coordinates', {

type: 'point',

mode: 'xy',

srid: 4326,

}).notNull(),

});

export const databaseSchema = {

locations,

};

Above, we specify the Spatial Reference System Identifier (SRID). This number tells PostGIS how to interpret the coordinates. It specifies one of several coordinate systems used to represent the data.

In SRID 4326, the coordinates are defined in latitude and longitude.
In SRID 3857, the coordinates are specified in meters on a flat map.

If two sets of coordinates use different SRIDs, they are based on different systems and won’t line up correctly. For example, comparing latitude/longitude directly to flat map coordinates will give incorrect results.

The default SRID in PostGIS is 0, which means the data has no defined coordinate system. It’s good practice to define the SRID for our data explicitly.

Let’s create the SQL migration to add our table to the database.

If you want to know more about migrations with the Drizzle ORM, check out API with NestJS #176. Database migrations with the Drizzle ORM

1	npx drizzle-kit generate --name add-locations-table

database-schema.ts

CREATE TABLE IF NOT EXISTS "locations" (

"id" serial PRIMARY KEY NOT NULL,

"name" text NOT NULL,

"coordinates" geometry(point) NOT NULL

);

Unfortunately, right now, Drizzle ORM has a bug that causes it to ignore the provided SRID. To deal with that, we have to adjust our migration manually. Let’s also add a line ensuring the PostGIS extension is set up.

database-schema.ts

CREATE EXTENSION IF NOT EXISTS postgis;

CREATE TABLE IF NOT EXISTS "locations" (

"id" serial PRIMARY KEY NOT NULL,

"name" text NOT NULL,

"coordinates" geometry(point, 4326) NOT NULL

);

Calculating the distance between two points

Let’s insert a few locations into our database:

Empire State Building in New York
Santa Monica Pier in the Los Angeles County
Times Square in New York

Let’s calculate the distance between the Empire State Building and the Santa Monica Pier. To do that, we can use the ST_DistanceSphere function built into PostgreSQL.

SELECT ST_DistanceSphere(

(SELECT coordinates FROM locations WHERE id = 1),

(SELECT coordinates FROM locations WHERE id = 2)

) as distance;

The result is roughly 3960 kilometers (about 2460 miles). What’s crucial is that the ST_DistanceSphere function takes into account that Earth is a sphere. To use it with the Drizzle ORM, we need to provide the raw SQL.

locations.service.ts

import { Injectable, NotFoundException } from '@nestjs/common';

import { DrizzleService } from '../database/drizzle.service';

import { databaseSchema } from '../database/database-schema';

import { sql } from 'drizzle-orm';

@Injectable()

export class LocationsService {

constructor(private readonly drizzleService: DrizzleService) {}

async getDistanceBetweenLocations(

firstLocationId: number,

secondLocationId: number,

) {

const queryResult = await this.drizzleService.db.execute(

sql`

SELECT ST_DistanceSphere(

(SELECT coordinates FROM ${databaseSchema.locations} WHERE id = ${firstLocationId}),

(SELECT coordinates FROM ${databaseSchema.locations} WHERE id = ${secondLocationId})

) AS distance;

);

const distance = queryResult.rows.pop()?.distance;

if (distance === null) {

throw new NotFoundException();

}

return distance;

}

// ...

}

The Earth is not a perfect sphere

What’s interesting is that ST_DistanceSphere assumes that Earth is a perfect sphere. However, this is not the case. To be more precise, we can use the ST_DistanceSpheroid function, which accounts for Earth’s ellipsoidal shape.

SELECT ST_DistanceSpheroid(

(SELECT coordinates FROM locations WHERE id = 1),

(SELECT coordinates FROM locations WHERE id = 2),

'SPHEROID["WGS 84",6378137,298.257223563]'

) AS distance;

By providing SPHEROID["WGS 84",6378137,298.257223563] we specify the Earth’s shape, using the WGS84 model.

The above query results in roughly 3969 kilometers (about 2466 miles). It is 9 kilometers more than the ST_DistanceSphere function returned. If we want to calculate big distances, taking the Earth’s shape into account can give us more precise results.

Getting locations in a certain radius

Another very useful feature is finding locations in a certain radius. To do that, we need to use the ST_DWithin function built into PostGIS.

So far, we’ve been using the geometry data type built into PostGIS that treats Earth as a flat 2D plane. However, when combined with functions such as ST_DistanceSpheroid, which we used above, it can calculate distances on a spherical Earth.

Alternatively, PostGIS implements the geography data type, which automatically accounts for the Earth’s ellipsoidal shape. Unfortunately, the Drizzle ORM does not currently support this type of data. To use the ST_DWithin function, we need to convert our data to geography on the fly.

SELECT * FROM locations

WHERE ST_DWithin(

coordinates::geography,

(SELECT coordinates::geography FROM locations WHERE id = 1),

5000 -- Radius in meters

);

Above, we find all the locations in a 5-kilometer radius of the Empire State Building in New York.

We can exclude the Empire State Building from our results to receive more meaningful results.

SELECT * FROM locations

WHERE id != 1

AND ST_DWithin(

coordinates::geography,

(SELECT coordinates::geography FROM locations WHERE id = 1),

5000 -- Radius in meters

);

To use ST_DWithin with the Drizzle ORM, we need to incorporate raw SQL into our code. Drizzle ORM handles most of the query, while the raw SQL is only used partly in the WHERE clause.

locations.service.ts

import { Injectable } from '@nestjs/common';

import { DrizzleService } from '../database/drizzle.service';

import { databaseSchema } from '../database/database-schema';

import { ne, sql, and } from 'drizzle-orm';

@Injectable()

export class LocationsService {

constructor(private readonly drizzleService: DrizzleService) {}

getLocationsInRadius(locationId: number, radiusInMeters: number) {

return this.drizzleService.db

.select()

.from(databaseSchema.locations)

.where(

and(

ne(databaseSchema.locations.id, locationId),

sql`ST_DWithin(

${databaseSchema.locations.coordinates}::geography,

(SELECT ${databaseSchema.locations.coordinates}::geography FROM ${databaseSchema.locations} WHERE id = ${locationId}),

${radiusInMeters}

)`,

);

}

// ...

}

Summary

In this article, we learned how to use PostGIS with the Drizzle ORM to calculate the distance between two coordinates and find all locations within a certain radius.

PostgreSQL offers many functionalities for various coordinate calculations thanks to the PostGIS extension. While the integration with Drizzle ORM isn’t perfect, we can work around most problems to get the job done. Assuming that the Drizzle team continues to improve the ORM, it has the potential to become a solid choice for handling spatial data.

Series Navigation<< API with NestJS #182. Storing coordinates in PostgreSQL with Drizzle ORMAPI with NestJS #184. Storing PostGIS Polygons in PostgreSQL with Drizzle ORM >>