SIMAP.ch API Integration

This document describes the SIMAP.ch public procurement API that the simap-mcp server integrates with. It covers the available endpoints, data structures, request/response formats, and API design principles of the Swiss public procurement platform.

For information about how the simap-mcp codebase implements the API client and handles requests, see SimapClient in src/api/client.ts32-101 For details about the MCP tools that expose this API functionality, see the tool registrations in src/server.ts32-51

API Overview

The SIMAP.ch API is a RESTful HTTP API provided by Switzerland's public procurement platform. It offers read-only access to public tender information, nomenclature codes, and reference data without requiring authentication for public endpoints.

Base Configuration:

• Base URL: https://www.simap.ch/api src/api/endpoints.ts5
• Protocol: HTTPS only
• Authentication: None required for public endpoints used by this server.
• Response Format: JSON (Accept: application/json) src/api/client.ts67
• Character Encoding: UTF-8
• Timezone: Europe/Zurich (Swiss time)

The API uses a "Domain before version" URL structure (e.g., /publications/v2/... rather than /v1/publications/...), allowing a single backend to implement multiple API versions simultaneously src/api/endpoints.ts7-31

Sources: src/api/endpoints.ts5-31 src/api/client.ts64-70

Endpoint Categories

The simap-mcp server uses three categories of SIMAP API endpoints, defined in src/api/endpoints.ts7-31:

Category	Version	Purpose	Code Constant
Publications	v1, v2	Search and retrieve tender publications	ENDPOINTS.PROJECT_SEARCH
Codes	v1	Query nomenclature classification systems	ENDPOINTS.CPV_SEARCH, etc.
Reference Data	v1	Retrieve cantons, institutions, offices	ENDPOINTS.CANTONS, etc.

API Endpoint Mapping

The following diagram bridges the "Natural Language Space" of the API domains to the "Code Entity Space" of ENDPOINTS constants in src/api/endpoints.ts

Title: SIMAP API Endpoint Mapping

Sources: src/api/endpoints.ts7-31

Publications Endpoints

Project Search - GET /publications/v2/project/project-search

Searches for public procurement projects. Although the simap-mcp client uses GET for consistency across its internal SimapClient.get() method src/api/client.ts47 the API accepts complex filtering via query parameters.

Key Request Parameters (Mapped from Tool Inputs):

• search: Full-text search term.
• newestPublicationFrom / newestPublicationUntil: Date range (YYYY-MM-DD).
• projectSubTypes: Array of sub-types (e.g., construction, service).
• orderAddressCantons: Array of 2-letter canton codes.
• cpvCodes: Array of 8-digit strings.
• lastItem: Opaque pagination token for retrieving the next set of results.

Sources: src/api/endpoints.ts9 src/api/client.ts47

Project Header & Details

• Project Header: GET /publications/v2/project/{projectId}/project-header. Provides metadata about the project including titles and lot information src/api/endpoints.ts10-11 Note: lotTitle in the response is treated as .nullish() because the API may omit it CHANGELOG.md58 src/types/api.ts27
• Publication Details: GET /publications/v1/project/{projectId}/publication-details/{publicationId}. Provides the full content of a specific publication. Since v1.2.0, this integration supports a fullRaw mode which leverages Zod .passthrough() to return the complete API response without filtering CHANGELOG.md63 src/types/api.ts106-110
• Past Publications: GET /publications/v1/publication/{publicationId}/past-publications. Retrieves the history of publications for a specific notice src/api/endpoints.ts14-15

Sources: src/api/endpoints.ts10-15 CHANGELOG.md58-63 src/types/api.ts27-110

Nomenclature Code Endpoints

The SIMAP API provides access to four classification systems. Each system uses a standardized pattern for search and hierarchical browsing src/api/endpoints.ts18-25

System	Code Format	Example
CPV	8 digits	72000000
BKP	1-3 digits + decimal	211, 3.4
NPK	3 digits	123
OAG	Dot-separated groups	1.10, 2.3.5

Code Search Pattern

The search_*_codes tools use the /search endpoints. The API returns an array of code objects containing the code identifier and multilingual labels. Tree-based browsing uses the base endpoints (e.g., /codes/v1/cpv) with a parent code as a query parameter src/api/endpoints.ts19-25

Sources: src/api/endpoints.ts18-25

Data Structures and Formats

Multilingual Objects (Translation)

Most text fields are returned as a Translation object containing keys for the four supported languages: de, fr, it, and en src/types/api.ts49-206 Fields are often nullish depending on the original publication language.

Pagination Structure

List responses include a pagination mechanism using lastItem (a string token used to fetch the next page) and itemsPerPage src/types/api.ts71

API Integration Architecture

The following diagram illustrates the flow from the SimapClient class to the SIMAP.ch API, including the rate-limiting logic.

Title: API Request Flow Architecture

Sources: src/api/client.ts32-101 src/api/endpoints.ts5-31

API Design Principles

1. Read-Only Public Access: The simap-mcp server utilizes public endpoints that do not require authentication.
2. Rate Limiting: The SimapClient implements a SlidingWindowRateLimiter (default 60 req/min) to ensure fair usage and prevent IP blocking src/api/client.ts38-48 src/api/rate-limiter.ts27-30 It uses a FIFO queue to guarantee order src/api/rate-limiter.ts7-9
3. Validation: All API responses are validated at runtime using Zod schemas to ensure data integrity before processing src/api/client.ts93-95 In v1.2.4, Zod was updated to ^4.4.3 to handle specific edge cases in discriminatedUnion and preprocess CHANGELOG.md16
4. Error Handling: The client throws a SimapApiError containing the status code and endpoint for non-OK responses src/api/client.ts72-78 src/types/api.ts10-19
5. Debug Mode: When SIMAP_MCP_DEBUG=1 (or "true") is set, the client logs full request details including duration, response status, and byte size to stderr src/api/client.ts15-88

Sources: src/api/client.ts15-95 src/api/rate-limiter.ts7-30 src/types/api.ts10-19 CHANGELOG.md16