Public API Types - Route-based Organisation

This directory contains all public API types organised by route structure, making it easy to find and use the correct types for each API endpoint.

📖 Description

The Vepler Area Reference API is a comprehensive geographic data service that provides detailed information about UK administrative boundaries, geographic entities, connectivity metrics, and location-based services. This API enables developers to query spatial data, retrieve connectivity scores, search for locations, and access detailed geographic information across England, Scotland, Wales, and Northern Ireland.

The service supports a wide range of geographic types including counties, districts, wards, parishes, output areas, and more, making it ideal for applications requiring detailed UK geographic data integration. Whether you're building property platforms, demographic analysis tools, or location-based services, this API provides the foundational geographic data you need.

📁 Folder Structure

src/types/public/
├── common.ts              # Global shared types (GeographicEntityType, etc.)
├── index.ts               # Export all types and route namespaces
└── routes/
    ├── areas/                  # /api/areas/* endpoints
    │   ├── index.ts           # Export all areas types
    │   ├── common.ts          # Areas-specific shared types (GeographicEntityResponse, etc.)
    │   ├── within.ts          # /api/areas/within
    │   ├── border.ts          # /api/areas/border/{targetType}/{targetCode}/{sourceType}
    │   ├── children.ts        # /api/areas/children/{parentCode}/{childType?}
    │   ├── query.ts           # /api/areas/query/{type}
    │   └── get-areas.ts       # /api/areas/{field}/{ids}
    ├── connectivity/          # /api/connectivity/* endpoints
    │   ├── index.ts           # Export all connectivity types
    │   ├── common.ts          # Connectivity-specific shared types (scores, data sources, etc.)
    │   └── get-connectivity-scores.ts  # /api/connectivity/scores/{geographicCodes}
    ├── search/                # /api/search/* endpoints
    │   ├── index.ts           # Export all search types
    │   ├── common.ts          # Search-specific shared types (SearchResult, etc.)
    │   └── get-autocomplete.ts  # /api/search/autocomplete
    ├── metrics/               # /api/metrics/* endpoints
    │   ├── index.ts           # Export all metrics types
    │   ├── common.ts          # Metrics-specific shared types (MetricValue, etc.)
    │   ├── get-metric-values.ts  # /api/metrics/values
    │   └── ingest-metric.ts   # /api/metrics/ingest
    ├── poi/                   # /api/poi/* endpoints
    │   ├── index.ts           # Export all POI types
    │   ├── common.ts          # POI-specific shared types (POIFeature, etc.)
    │   ├── get-nearest.ts     # /api/poi/nearest
    │   └── get-poi-bounds.ts  # /api/poi/bounds
    ├── geographic/            # /api/geographic/* endpoints
    │   ├── index.ts           # Export all geographic utility types
    │   ├── common.ts          # Geographic-specific shared types (ResolutionStrategy, etc.)
    │   ├── resolve-geography.ts      # /api/geographic/resolve
    │   ├── get-types.ts       # /api/geographic/types
    │   └── check-capability.ts       # /api/geographic/capability
    └── index.ts               # Export all route namespaces

🎯 Usage Examples

Import by Route Namespace (Recommended)

import { Areas, Connectivity, Search, POI } from '../../types/public/routes';

// Areas API types
const withinParams: Areas.WithinQueryParams = {
  lat: 51.5074,
  lng: -0.1278,
  radius: 1000,
  type: 'ward,parish'
};

const borderResponse: Areas.BorderResponse = {
  success: true,
  result: {
    target: { code: 'E05000001', name: 'City of London', type: 'ward' },
    sourceType: 'district',
    areas: [],
    count: 0
  }
};

// Connectivity API types
const connectivityScore: Connectivity.ConnectivityScore = {
  geographicCode: 'E00000001',
  dataSources: {},
  metadata: { processingTimeMs: 50 }
};

// Search API types
const autocompleteParams: Search.GetAutocompleteQueryParams = {
  q: 'London',
  limit: 10
};

// POI API types
const nearestPOIParams: POI.GetNearestPOIQueryParams = {
  lat: 51.5074,
  lng: -0.1278,
  types: 'RETAIL,FERRY,BUS',
  radius: 1000,
  limit: 5
};

Import Specific Types

// Import global common types
import { GeographicEntityType, Dictionary, GeoJSONGeometry } from '../../types/public/common';

// Import route-specific types
import { WithinQueryParams, BorderResponse } from '../../types/public/routes/areas';
import { ConnectivityScore } from '../../types/public/routes/connectivity';
import { GetAutocompleteQueryParams } from '../../types/public/routes/search';
import { GetNearestPOIQueryParams, GetNearestPOIResponse } from '../../types/public/routes/poi';

Legacy Import (Backwards Compatible)

import { 
  GeographicEntityResponse,
  ConnectivityScore,
  SearchResult 
} from '../../types/public/api/endpoints/areas';  // Still works

📋 Route Coverage

✅ Areas API (/api/areas/*)

• Within: Point-in-polygon spatial queries
• Border: Find areas that border a given area
• Children: Get child areas within a parent area
• Query: Search areas by type with filters
• Get Areas: Retrieve areas by field and IDs

✅ Connectivity API (/api/connectivity/*)

• Get Connectivity Scores: Retrieve broadband and mobile connectivity scores

✅ Search API (/api/search/*)

• Get Autocomplete: Location search with smart type detection

✅ Metrics API (/api/metrics/*)

• Get Metric Values: Retrieve metric data with filtering
• Ingest Metric: Submit new metric data

✅ POI API (/api/poi/*)

• Get Nearest: Find nearest points of interest by category (e.g., RETAIL, FERRY, BUS)
• Get POI Bounds: Get POI data within bounding box (GeoJSON/MVT)

✅ Geographic API (/api/geographic/*)

• Resolve Geography: Map input geography to supported tiers
• Get Types: List all supported geography types
• Check Capability: Check resolution capabilities

🔧 Type Design Principles

1. Route-Aligned Structure

Each folder corresponds exactly to an API route, making it intuitive to find the right types.

2. Layered Common Types

• Global common types (common.ts): Types shared across all routes (e.g., GeographicEntityType, Dictionary)
• Route-specific common types (routes/{route}/common.ts): Types shared within a specific route

3. Endpoint-Specific Types

Each endpoint has its own file with request/response types specific to that endpoint.

4. Consistent Naming

• Query parameters: {EndpointName}QueryParams
• Path parameters: {EndpointName}PathParams
• Response types: {EndpointName}Response
• Error responses: {RouteName}ErrorResponse

5. Full Documentation

All types include comprehensive JSDoc comments explaining purpose and usage.

6. Real Working Types

These are the actual types used by the API handlers, not theoretical definitions.

🚀 Benefits

1. Easy Navigation: Find types by API route structure
2. Namespace Isolation: Areas.WithinResponse vs Search.SearchResponse
3. Logical Grouping: Related types are collocated
4. Backwards Compatible: Legacy imports still work
5. Type Safety: Full TypeScript support with IntelliSense
6. Customer Ready: Can be published as external package

📦 Publishing

These types can be built and published as a separate npm package:

npm run build:types
npm publish @vepler/area-reference-types

External consumers can then use:

import { Areas, Connectivity } from '@vepler/area-reference-types';