Public API Types - Route-based Organisation

📝 Description

This TypeScript library provides comprehensive type definitions for the Vepler Safety Service API. The service offers location-based crime statistics, safety metrics, and neighbourhood watch data across England and Wales. Our API enables developers to query crime data by geographic area, analyze crime trends over time, calculate crime scores, and access neighbourhood watch scheme information.

The type library follows a route-based organisation structure, with each API endpoint having dedicated request and response types. This approach ensures type safety, improved developer experience, and seamless integration with the Vepler Safety Service.

📁 Folder Structure

src/types/public/
├── routes/
│   ├── catalog/
│   │   ├── index.ts
│   │   └── get-catalog.ts
│   ├── crime/
│   │   ├── index.ts
│   │   ├── get-area-stats.ts
│   │   ├── get-category-stats.ts
│   │   └── get-crime-data.ts
│   ├── geography/
│   │   ├── index.ts
│   │   └── get-metrics.ts
│   ├── neighborhood-watch/
│   │   ├── index.ts
│   │   ├── get-by-area.ts
│   │   ├── get-by-location.ts
│   │   └── get-scheme-details.ts
│   └── index.ts
├── index.ts
└── README.md

🎯 Usage Examples

// Namespace import (recommended)
import { CatalogTypes, CrimeTypes, GeographyTypes, NeighborhoodWatchTypes } from '@vepler/safety-types';

// Specific import
import { GetCatalogQueryParams, GetCatalogResponse } from '@vepler/safety-types/routes/catalog';

// Direct route import
import { GetMetricsQueryParams, GetMetricsResponse } from '@vepler/safety-types/routes/geography';

📋 Route Coverage

/api/catalog

• Get Catalog: Retrieve available data periods and processing status by country

/api/crime

• Get Area Stats: Area-based crime statistics with boundary data
• Get Category Stats: Crime statistics grouped by category and time period
• Get Crime Data: Individual crime incident data with location details

/api/geography

• Get Metrics: Comprehensive geographic crime metrics with time series and percentage changes

/api/neighborhood-watch

• Get By Area: Neighborhood watch schemes within specific geographic areas
• Get By Location: Proximity-based search for neighborhood watch schemes
• Get Scheme Details: Detailed information about specific neighborhood watch schemes

🔧 Type Design Principles

• Route-based organisation: Each API route has its own namespace with dedicated request/response types • Consistent naming: All types follow {EndpointName}QueryParams and {EndpointName}Response conventions • Error handling: Standardised {RouteName}ErrorResponse types for each route namespace • Type safety: Explicit TypeScript interfaces with comprehensive JSDoc documentation • Modern standards: Current API specifications with clean, consistent interfaces • Extensibility: Modular structure allows easy addition of new routes and endpoints

🚀 Benefits

• Route isolation: Types are organised by API route, making them easier to locate and maintain • Namespace clarity: Import exactly what you need without type name conflicts • IntelliSense support: Full autocomplete and type checking in modern IDEs • Documentation: Rich JSDoc comments provide context and usage examples • Stable contracts: Well-defined API interfaces ensure consistent integration experience • Build safety: TypeScript compilation failures prevent deployment of broken type definitions • Validation ready: Types designed to work seamlessly with runtime validation libraries • Future-proof: Scalable structure ready for new API endpoints and features

📦 Publishing

Build the types library:

pnpm build:types

Import in your project:

import { GeographyTypes } from '@vepler/safety-types';
// or
import { GetMetricsQueryParams } from '@vepler/safety-types/routes/geography';