Package Exports

@tenderlift/simap-client

Readme

@tenderlift/simap-client

TypeScript client for the SIMAP (Swiss Public Procurement) API, auto-generated from the official OpenAPI specification.

⚠️ Non-affiliation Notice: This is an unofficial, open-source library for the SIMAP API. It is developed and maintained independently by TenderLift. While SIMAP has graciously approved the open-sourcing of this library, they do not control, endorse, or bear any responsibility for it. For official information, visit simap.ch.

Features

Full TypeScript support with comprehensive type definitions
Multi-runtime compatible: Node.js 20+, Cloudflare Workers, Vercel/Netlify Edge
Lightweight: <10KB gzipped (5.3KB ESM, 7.28KB CJS)
Auto-generated from official SIMAP OpenAPI specification
Built-in error handling with typed error responses
Authentication helpers for token-based auth
Well tested: 67 tests across Node.js and Worker environments

Try it Online

Launch a pre-configured development environment in your browser with GitHub Codespaces to explore the SIMAP client examples instantly.

Installation

npm install @tenderlift/simap-client
# or
pnpm add @tenderlift/simap-client
# or
yarn add @tenderlift/simap-client

Quick Start

Basic Usage (Node.js/Edge)

import { client, listCantons, getPublicProjectSearch } from '@tenderlift/simap-client';

// Configure the client (optional - defaults to SIMAP API)
client.setConfig({
  baseUrl: 'https://www.simap.ch/api',
  headers: {
    // Add authentication if needed
    // 'Authorization': `Bearer ${token}`
  },
});

// Fetch reference data
const cantons = await listCantons();
console.log(cantons.data); // List of Swiss cantons

// Search for projects
const projects = await getPublicProjectSearch({
  query: {
    orderAddressCantons: ['TI', 'GR'],
    search: 'construction'
  }
});
console.log(projects.data?.projects);

Error Handling

import { ensureOk, HttpError } from '@tenderlift/simap-client';

try {
  const response = await listCantons();
  const data = ensureOk(response); // Throws HttpError if response is not ok
  console.log(data);
} catch (error) {
  if (error instanceof HttpError) {
    console.error(`HTTP ${error.status}: ${error.message}`);
    console.error('Error data:', error.data);
  }
}

Authentication

import { withAuth } from '@tenderlift/simap-client';

// Add authentication to all requests
const auth = { token: 'your-api-token' };
client.interceptors.request.use((request) => {
  return withAuth(auth)(request);
});

Browser Support

❌ Direct browser usage is not supported because the SIMAP API does not send CORS headers.

If you need to use this client in a browser application, you must:

Set up a proxy server (your backend, edge function, or development server)
Route SIMAP API requests through your proxy
Configure the client to use your proxy URL

Example proxy setup with Vite:

// vite.config.js
export default {
  server: {
    proxy: {
      '/api': {
        target: 'https://www.simap.ch',
        changeOrigin: true,
      }
    }
  }
}

API Documentation

Available Endpoints

Reference Data

listCantons() - Get all Swiss cantons
listCountries() - Get all countries
listLanguages() - Get supported languages
listActivities() - Get TED activity codes
listCriteria() - Get selection criteria

Project Search

getPublicProjectSearch(options) - Search public procurement projects
getProjectHeaderById(options) - Get project details by ID
getPublicationDetail(options) - Get publication details

Classification Codes

listCPVCodes() - Common Procurement Vocabulary codes
listCPCCodes() - Central Product Classification codes
listBKPCodes() - Swiss construction classification codes
listNPKCodes() - Swiss standard position catalog codes

Response Structure

All API methods return a response object with the following structure:

interface ApiResponse<T> {
  data?: T;        // Response data (undefined on error)
  error?: unknown; // Error information
  response: Response; // Raw fetch Response object
}

Development

See CONTRIBUTING.md for development setup and guidelines.

Scripts

pnpm build - Build the library
pnpm test - Run all tests
pnpm typecheck - Type checking
pnpm lint - Run linter
pnpm size - Check bundle size

Troubleshooting

Common Issues

TypeScript Types Not Found

Ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Network Errors in Node.js

For Node.js versions before 20, you may need a fetch polyfill:

npm install node-fetch

Authentication Errors

Ensure your API token is valid and properly formatted in the Authorization header.

License

See LICENSE file for details.

Links

Built with ❤️ for the Swiss open-source community