JSPM

@lineai/municipal-intel

1.2.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 26
  • Score
    100M100P100Q48637F
  • License MIT

Access municipal planning applications, building permits, and construction activity data from major US cities

Package Exports

  • @lineai/municipal-intel
  • @lineai/municipal-intel/build/main/index.js
  • @lineai/municipal-intel/build/module/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@lineai/municipal-intel) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@lineai/municipal-intel

Access municipal planning applications, building permits, and construction activity data from major US cities.

Overview

@lineai/municipal-intel provides a unified interface to access local government data from major US cities. Built with TypeScript for maximum type safety, it features a hybrid architecture with built-in sources and runtime extensibility.

Features

  • Unified API: Single interface for multiple municipal data sources
  • Real-time Data: Access live permit and planning application data
  • TypeScript Native: Built-in sources defined in TypeScript (no JSON dependencies)
  • Runtime Extensible: Add new cities dynamically without package updates
  • Universal Socrata Token: Single token works across all Socrata portals
  • Type Safety: Full TypeScript support with Zod schema validation
  • Rate Limiting: Built-in rate limiting and retry logic

Supported Cities

Built-in Sources (Ready to Use)

  • California: San Francisco, Los Angeles
  • New York: New York City (all 5 boroughs)

Runtime Registration (Add Your Own)

  • Any Socrata Portal: Add any city with Socrata-based open data
  • Custom APIs: Register custom municipal APIs
  • Extensible: No package updates needed for new cities

See docs/ADD_NEW_SOURCE.md for adding new sources.

Installation

npm install @lineai/municipal-intel

Quick Start

import { createMunicipalIntel } from '@lineai/municipal-intel';

// Create client instance
const municipal = createMunicipalIntel({
  debug: true
});

// Set universal Socrata token (works for all cities)
municipal.setSocrataToken(process.env.SOCRATA_TOKEN);

// Search for construction permits in San Francisco
const results = await municipal.search({
  sources: ['sf'],
  types: ['permit', 'construction'],
  keywords: ['renovation', 'construction'],
  minValue: 100000,
  limit: 10
});

console.log(`Found ${results.total} projects`);
results.projects.forEach(project => {
  console.log(`${project.title} - ${project.address} - $${project.value}`);
});

Authentication

Get a single free app token that works across all Socrata portals:

  1. Visit any Socrata portal (e.g., data.sfgov.org)
  2. Sign up → Developer Settings → Create App Token
  3. Use this same token for all cities!
const municipal = createMunicipalIntel();
municipal.setSocrataToken(process.env.SOCRATA_TOKEN);

Rate limits:

  • With token: 1000 requests/hour per portal
  • Without token: Shared pool, very limited

API Reference

Search Projects

const results = await municipal.search({
  // Location filters
  sources: ['sf', 'nyc'],           // Specific sources
  states: ['CA', 'NY'],             // By state
  cities: ['San Francisco'],        // By city name
  addresses: ['Market Street'],     // By address
  zipCodes: ['94102'],             // By ZIP code
  
  // Project filters
  types: ['permit', 'planning'],    // Project types
  statuses: ['approved', 'issued'], // Current status
  keywords: ['renovation'],         // Keywords
  
  // Date filters
  submitDateFrom: new Date('2024-01-01'),
  submitDateTo: new Date('2024-12-31'),
  
  // Value filters
  minValue: 50000,
  maxValue: 1000000,
  
  // Pagination
  limit: 50,
  offset: 0,
  
  // Sorting
  sortBy: 'submitDate',
  sortOrder: 'desc'
});

Get Specific Project

const project = await municipal.getProject('sf', 'sf-202401234567');

List Available Sources

// All sources
const allSources = municipal.getSources();

// Filter by criteria
const apiSources = municipal.getSources({ 
  type: 'api', 
  priority: 'high' 
});

// By state
const caSources = municipal.getSources({ state: 'ca' });

Health Checks

const health = await municipal.healthCheck('sf');
console.log(`Status: ${health.status}, Latency: ${health.latency}ms`);

Runtime Source Registration

Add new cities without updating the package:

// Register a new Florida city
municipal.registerSource({
  id: 'miami',
  name: 'Miami-Dade County',
  state: 'FL',
  type: 'api',
  api: {
    type: 'socrata',
    baseUrl: 'https://opendata.miamidade.gov',
    datasets: {
      buildingPermits: {
        endpoint: '/resource/8wbx-tpnc.json',
        name: 'Building Permits',
        fields: ['permit_number', 'status', 'issue_date', 'address']
      }
    },
    fieldMappings: {
      id: 'permit_number',
      status: 'status',
      submitDate: 'issue_date',
      address: 'address'
    }
  },
  priority: 'high'
});

// Now you can search Miami data
const miamiResults = await municipal.search({ sources: ['miami'] });

// Remove runtime source
municipal.unregisterSource('miami');

Data Types

MunicipalProject

interface MunicipalProject {
  // Required
  id: string;              // Unique identifier
  source: string;          // Source municipality
  type: ProjectType;       // 'permit' | 'planning' | 'construction'
  title: string;           // Project description
  address: string;         // Location
  status: ProjectStatus;   // Current status
  submitDate: Date;        // Filed date
  
  // Optional
  approvalDate?: Date;     // Approval date
  value?: number;          // Estimated cost
  applicant?: string;      // Applicant name
  contractor?: string;     // Contractor
  description?: string;    // Details
  coordinates?: { lat: number; lng: number };
  documents?: Document[];  // Related files
  url?: string;           // Details page
}

Examples

Monitor New Permits

// Get recent permits from multiple sources
const recent = await municipal.search({
  sources: ['sf', 'nyc', 'la'],
  types: ['permit'],
  submitDateFrom: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000), // Last 7 days
  sortBy: 'submitDate',
  sortOrder: 'desc'
});

Construction Projects by Value

// High-value construction projects
const bigProjects = await municipal.search({
  types: ['construction', 'renovation'],
  minValue: 1000000,
  statuses: ['approved', 'issued'],
  sortBy: 'value',
  sortOrder: 'desc'
});
// Projects in specific area
const localProjects = await municipal.search({
  addresses: ['Market Street', 'Mission Street'],
  zipCodes: ['94102', '94103'],
  limit: 20
});

Environment Variables

# .env
SOCRATA_TOKEN=your-universal-socrata-app-token

Note: A single Socrata token works across all Socrata portals (San Francisco, NYC, Miami, etc.)

Error Handling

import { MunicipalDataError, RateLimitError } from '@lineai/municipal-intel';

try {
  const results = await municipal.search({ sources: ['sf'] });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log('Rate limited, retry after:', error.details?.resetTime);
  } else if (error instanceof MunicipalDataError) {
    console.log('API error:', error.message, 'Source:', error.source);
  }
}

Development

# Install dependencies
yarn install

# Build
yarn build

# Test
yarn test:unit

# Lint and fix
yarn fix

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Add tests for new functionality
  4. Ensure all tests pass
  5. Submit a pull request

Documentation

License

MIT