API Documentation

Complete API documentation for Mapfolio's public API - Access Swiss company data programmatically

Interactive API Documentation
Explore all available endpoints, request parameters, response schemas, and try out API calls directly in your browser.
View OpenAPI Documentation

Overview

The Mapfolio API provides programmatic access to Swiss company data through a RESTful interface. All endpoints are documented using the OpenAPI 3.0 specification, ensuring consistency and ease of integration.

Getting Started

Authentication

The Mapfolio API uses API key authentication. You can obtain your API key from your account settings.

API Key Header:

X-API-Key: mapf_your_api_key_here

Bearer Token (Alternative):

Authorization: Bearer mapf_your_api_key_here

Base URL

All API requests should be made to:

https://mapfolio.app

Rate Limiting

API requests are rate-limited to ensure fair usage:

  • Authenticated requests: 1000 requests per hour per API key
  • Unauthenticated requests: 10 requests per hour per IP address

Rate limit information is included in response headers:

  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Unix timestamp when the limit resets

Available Endpoints

Company Search

Search for companies with advanced filtering options:

  • Text search across company names
  • Filter by canton (Swiss cantons)
  • Filter by company status
  • Pagination support

Company Details

Retrieve detailed information about specific companies:

  • Company profile data
  • Location information
  • Legal status
  • Registration details

Statistics

Access aggregated statistics about Swiss companies:

  • Overall company counts
  • Canton-level statistics
  • Letter-based distributions
  • Two-letter combination counts

Autocomplete

Get autocomplete suggestions for:

  • Company names
  • Cities
  • Postal codes

Random Companies

Retrieve random company samples for testing and exploration.

Response Format

All successful API responses follow a consistent structure:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

Error responses include detailed information:

{
  "error": "Error message",
  "details": "Additional error details"
}

Error Codes

  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Missing or invalid API key
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server-side error

OpenAPI Specification

The complete OpenAPI 3.0 specification is available at:

You can use the OpenAPI specification with any compatible tool:

  • Swagger UI
  • Postman
  • Insomnia
  • Code generators for client libraries

Code Examples

cURL

curl -H "X-API-Key: mapf_your_api_key_here" \
  https://mapfolio.app/api/search?q=technology

JavaScript (Fetch)

const response = await fetch('https://mapfolio.app/api/search?q=technology', {
  headers: {
    'X-API-Key': 'mapf_your_api_key_here'
  }
})
const data = await response.json()

Python (Requests)

import requests

headers = {'X-API-Key': 'mapf_your_api_key_here'}
response = requests.get(
  'https://mapfolio.app/api/search',
  params={'q': 'technology'},
  headers=headers
)
data = response.json()

Support

For API support and questions:

Terms of Use

By using the Mapfolio API, you agree to our Terms of Service and Privacy Policy. Please review rate limits and usage guidelines to ensure compliance.