Documentation

How FindHackEU publishes reliable European hackathon listings, and how to browse or reuse the approved data.

Browse Hackathons

Search and filter hackathons across Europe.

REST API

Read published hackathon data programmatically.

Interactive Map

Explore event locations on a clustered map.

From discovery to publication

FindHackEU is independently maintained by Gabriele Viganò. It grew from a discovery setup that surfaced two hackathons at a time to a multi-source pipeline that now finds more than 100 events across Europe. The goal is broader coverage without treating unverified search results as published facts.

1. Discover

Scheduled providers collect public event listings; web search and public submissions add candidates for review.

2. Validate

URLs are normalized, likely duplicates are reconciled, and available location data is checked and enriched.

3. Publish

Only approved, non-archived records appear on the website and in the public API. Candidate records never publish themselves.

Getting Started

FindHackEU brings together hackathons taking place across Europe. Its ingestion pipeline collects events from several sources, removes duplicates, and enriches available location data before entries appear in the public listing.

Key Features

  • Scheduled discovery: The pipeline refreshes the published dataset daily.
  • Filters: Narrow results by text, location and radius, topic, date, and event status.
  • Map: Review matching events on a clustered map.
  • Bookmarks: Save events in this browser for later.
  • Submissions: Suggest a missing event for moderation.
  • Public API: Access published data programmatically.
  • Responsive interface: Use the listing on desktop and mobile devices.

Internationalization

The public interface is available in multiple languages. App translations are maintained in i18n/; this page is currently written in English.

Available Languages

  • English
  • Italian
  • German
  • Spanish
  • French
  • Dutch
  • Portuguese
  • Polish
  • Romanian
  • Swedish

Contributors should update the JSON files in i18n/ together and keep their keys aligned. The translation context in contexts/translation-context.tsx provides the application's translation helpers.

Using the Platform

Browsing Hackathons

The listing presents each event as a card. Depending on the source data available, a card can include:

  • Event name: The published event title
  • Location: City, country, and location type when known
  • Dates: Start and end times, when supplied
  • Topics: Applicable event tags
  • Notes: Additional details provided by the source
  • Event link: The source page for registration or details

Filtering Options

Search

Match event names and available text.

Status

Switch between upcoming and past listings.

Location

Filter by country or city, or search within a radius of a chosen place.

Topics

Include one or more topics.

Date Range

Restrict results to a date range.

API Documentation

The read-only API exposes published hackathons as JSON. It is intended for reasonable use by applications and integrations.

Base URL

https://your-findhackeu-deployment.example/api

Replace the example host with the URL of the FindHackEU deployment you are querying.

Endpoints

GET/hackathons

Return published hackathons for the requested status.

Query Parameters

  • status — Optional; one of upcoming, past, or estimated. Defaults to upcoming.
  • limit — Optional page size from 1 to 100. If omitted, the API returns the complete matching dataset.
  • cursor — Opaque cursor returned asnextCursor from a paginated response. Use it only with the same status and limit.

Examples

GET /api/hackathons?status=upcoming GET /api/hackathons?status=upcoming&limit=25 GET /api/hackathons?status=upcoming&limit=25&cursor=<nextCursor>

Response Format

{ "data": [ { "id": "uuid", "name": "AI Hackathon Munich", "city": "Munich", "country_code": "DE", "location_type": "physical", "venue": null, "date_start": "2025-06-15T09:00:00+00:00", "date_end": "2025-06-16T18:00:00+00:00", "topics": ["AI", "Machine Learning"], "notes": "Bring your laptop and creativity!", "url": "https://example.com/hackathon", "source": "luma", "status": "upcoming", "is_new": true }, ... ] }

When limit is supplied, the response also includes nextCursor. It is null on the final page. Dates and optional details depend on what the original organizer publishes; country_code uses ISO 3166-1 alpha-2 codes, while location_type is one of physical, online,hybrid, or tbd.

Rate Limiting

In production, the public API applies these per-client limits:

  • Hourly limit: 100 requests per hour
  • Burst limit: 10 requests per minute
  • Limits are disabled outside production to support local development.

Error Codes

400

Bad Request

An invalid query parameter was supplied.

429

Too Many Requests

The production rate limit was exceeded.

500

Internal Server Error

The server could not complete the request.

503

Service Unavailable

The service is temporarily unavailable.

Bookmarks & Submitting Hackathons

Save events locally or suggest a missing one. Neither action requires an account.

Bookmarks

Select the heart on an event card to save it. Bookmarks stay in this browser's local storage and can be used to filter the listing.

Submit a Hackathon

Use the submission form to suggest a missing event. A maintainer reviews every submission before it can appear in the public listing.

Discord, Telegram, and X (Twitter) notifications are not currently active.

Technical Architecture

FindHackEU uses a TypeScript application, a Supabase PostgreSQL database, and a scheduled ingestion workflow.

Technology Stack

Frontend

  • Next.js 16 with App Router
  • TypeScript
  • Tailwind CSS
  • shadcn/ui components

Backend

  • Next.js Route Handlers
  • Supabase (PostgreSQL)
  • Row Level Security

Infrastructure

  • Deployment environment
  • GitHub Actions scheduled workflow
  • Daily ingestion schedule

Update Frequency

A scheduled workflow runs the ingestion pipeline once per day. Individual source failures are reported without preventing the remaining stages from completing.

Data quality

FindHackEU is a directory, not the event organizer. Always use the link on an event card for registration, eligibility, and last-minute changes. The pipeline is designed to make listings useful and transparent about their provenance, not to replace the organizer's information.

  • Source traceability: API records retain their provider in the source field and cards link back to the source event page.
  • Duplicate protection: normalized URLs and title/date matching prevent the same event being listed twice when providers overlap.
  • Human moderation: web-search discoveries and community submissions stay pending until a maintainer reviews them.
  • Honest uncertainty: unknown dates, venues, and location types remain unset or marked as to be determined; they are not invented by the service.

Contributing

FindHackEU is open source. Contributions that improve coverage, correctness, accessibility, or documentation are welcome.

How to Contribute

  • Report an issue: Use GitHub for a bug, missing event, or documentation problem. Open an issue
  • Contribute code: Create a focused change in your copy of the repository and open a pull request.
  • Suggest improvements: Describe the problem and proposed outcome in an issue before undertaking larger work.

Development Setup

# Clone the repository
git clone https://github.com/viganogabriele/FindHackEU.git
# Install dependencies
npm install
# Set up environment variables
cp .env.example .env.local
# Run development server
npm run dev

Support & Community

Use the channel that best fits the request.

GitHub Issues

Best for bug reports, proposed improvements, and technical discussion.

Open Issue

Email the Maintainer

FindHackEU is maintained by Gabriele Viganò. Use email for questions not suited to a public issue.

info@viganogabriele.com

Discord, Telegram, and X (Twitter) notification channels are not currently active.

Frequently Asked Questions

How often is the data updated?

The scheduled ingestion pipeline runs once per day.

Can I submit a hackathon that's missing?

Yes. Use the public submission form or open a GitHub issue with the event details. A maintainer reviews each suggestion before publication.

Is the API free to use?

The read-only API is publicly available. In production it is rate-limited to protect the service; see the API section above.

How do you determine if a hackathon is "European"?

The discovery pipeline uses source location data to retain events in European countries. Events with unresolved locations may remain available when the source explicitly identifies them as online or hybrid.

Can I use this data for my own project?

Yes. Use the public API within its production rate limits and attribute FindHackEU when its data materially supports your project.

Who maintains FindHackEU?

FindHackEU is maintained by Gabriele Viganò. It is an independent MIT-licensed project. Its starting inspiration was HackTrack EU, created by Lorenzo Palaia; FindHackEU now has its own architecture, infrastructure, and roadmap.

For further help, open a GitHub issue or contact the maintainer by email.