GeoData Placefinder

An open-source geocoding API and demo site that converts addresses into geographic coordinates (and vice versa) using Overture Maps data queried through DuckDB.

Features

• Geocoding — convert free-form addresses, place names, or categories into coordinates
• Reverse geocoding — find the nearest places to any latitude/longitude pair
• Nearest place — single closest match within a configurable radius
• Place detail — full Overture Maps record by place ID
• Zero external dependencies at runtime — DuckDB reads Overture Parquet files directly over HTTPS; no PostGIS, no Elasticsearch, no third-party API keys

---

Documentation

Full API reference is available on the live demo site at /docs, or read the source in lib/api-spec/openapi.yaml.

Endpoints

Method	Path	Description
GET	/api/health	Server status and cache info
GET	/api/search	Geocode by name, address, city, postcode, or category
GET	/api/reverse	Reverse geocode — places near a coordinate
GET	/api/places/nearest	Single closest place within a radius
GET	/api/places/:id	Full place detail by Overture place ID

Quick example

# Geocode by name
curl "https://geodataplacefinder.org/api/search?q=Eiffel+Tower"

# Reverse geocode
curl "https://geodataplacefinder.org/api/reverse?lat=48.8584&lon=2.2945"

# Nearest place within 500 m
curl "https://geodataplacefinder.org/api/places/nearest?lat=48.8584&lon=2.2945&max_distance_m=500"

---

Installation

Prerequisites

• Docker (recommended)
• Or: Node.js 20+ and pnpm 9+

Docker (recommended)

# 1. Clone the repository
git clone https://github.com/your-org/geodataplacefinder.git
cd geodataplacefinder

# 2. Build and start both services
docker compose up --build

The API server is available at http://localhost:8080 and the demo site at http://localhost:3000. The production deployment is at https://geodataplacefinder.org.

Note: On first start DuckDB fetches ~50 000 place records from Overture Maps S3 (~15 s). Subsequent restarts load the local cache instantly from data/places.duckdb.

Dockerfile (API server)

FROM node:20-alpine AS base
WORKDIR /app

# Install pnpm
RUN corepack enable && corepack prepare pnpm@latest --activate

# Install dependencies
COPY pnpm-workspace.yaml pnpm-lock.yaml package.json ./
COPY artifacts/api-server/package.json ./artifacts/api-server/
COPY lib/ ./lib/
RUN pnpm install --frozen-lockfile

# Build
COPY . .
RUN pnpm --filter @workspace/api-server run build

EXPOSE 8080
CMD ["node", "artifacts/api-server/dist/index.js"]

docker-compose.yml

version: "3.9"
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    environment:
      PORT: 8080
    volumes:
      - ./data:/app/data   # persist the DuckDB cache between restarts

  web:
    build:
      context: .
      dockerfile: artifacts/geodata-web/Dockerfile
    ports:
      - "3000:3000"
    environment:
      PORT: 3000
    depends_on:
      - api

Manual installation (without Docker)

# 1. Clone
git clone https://github.com/your-org/geodataplacefinder.git
cd geodataplacefinder

# 2. Install dependencies (requires Node.js 20+ and pnpm 9+)
pnpm install

# 3. Start the API server (port 8080)
pnpm --filter @workspace/api-server run dev

# 4. In a separate terminal, start the frontend (port 25276 by default)
pnpm --filter @workspace/geodata-web run dev

Environment variables

Variable	Default	Description
PORT	8080	API server port
SESSION_SECRET	—	Secret used for session signing (set for production)

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

---

License

GeoDataPlacefinder is released under the GNU General Public License v3.0. See LICENSE for the full text.

Data sourced from Overture Maps Foundation, released under CDLA Permissive 2.0.