How can we help you?

You want to understand what HelvAddress API offers and whether it's the right solution for your address validation needs.

HelvAddress API is a professional Swiss address validation and search service. It provides access to official Swiss address data from the Federal Register of Buildings and Dwellings (RBD/GWR). The API supports address lookup, autocomplete with relevance scoring, and address normalization/validation for all 26 Swiss cantons.

You're new to HelvAddress and want to know the steps to start using the API in your application.

To get started: 1) Sign up for an account on our website, 2) Obtain your API credentials (client_id and client_secret), 3) Authenticate using OAuth 2.0 to get an access token, 4) Start making API calls using the access token in the Authorization header. Check our API documentation for detailed examples and code snippets.

You want to understand the pricing structure and choose the right plan for your usage needs.

HelvAddress offers flexible pricing plans based on your API usage volume. We offer a free tier for testing and development, as well as paid plans for production use. Each plan includes a specific number of API calls per month. Contact our sales team for custom enterprise plans with higher volumes and dedicated support.

You need to authenticate your application to make API requests but are unsure about the authentication flow.

HelvAddress uses OAuth 2.0 for authentication. For server-to-server integration, use the Client Credentials flow: POST to /oauth2/token with grant_type=client_credentials, client_id, and client_secret. The response contains an access_token that you include in subsequent API requests as 'Authorization: Bearer {token}'.

Your API requests are returning 401 Unauthorized errors because the access token has expired.

Access tokens expire after a set period (typically 1 hour). You have two options: 1) Request a new access token using your client credentials, or 2) If you received a refresh_token, use the refresh_token grant type to obtain a new access token without re-authenticating. We recommend implementing automatic token refresh in your application.

When trying to authenticate, you receive an 'invalid_client' error and cannot obtain an access token.

This error occurs when the client credentials are incorrect. Verify that: 1) Your client_id is correct and active, 2) Your client_secret is exactly as provided (check for extra spaces), 3) If using Basic authentication, ensure the credentials are properly Base64 encoded. You can regenerate your client secret from the dashboard if needed.

You want to understand the API rate limits to design your application accordingly and avoid being throttled.

Rate limits depend on your subscription plan. The API returns rate limit information in response headers: X-RateLimit-Limit (max requests per window), X-RateLimit-Remaining (remaining requests), and Retry-After (seconds until reset when limited). If you exceed the limit, you'll receive a 429 Too Many Requests response. Consider implementing exponential backoff for retries.

You want to implement real-time address suggestions in your application but need guidance on using the autocomplete endpoint effectively.

The /addresses/autocomplete endpoint performs full-text search with relevance scoring. Pass your search query in the 'query' parameter. Use 'threshold' (0.0-1.0) to filter low-quality matches and 'limit' (max 20) to control result count. For best performance in typeahead interfaces, use a limit of 5-10 and debounce user input by 200-300ms to reduce API calls.

You have user-entered addresses that need to be validated and standardized against official Swiss address data.

Use the POST /addresses/normalize endpoint with the freeform address as plain text in the request body. The API returns a status (MATCHED, AMBIGUOUS, NOT_FOUND, or INVALID_INPUT) along with the best match and any alternative candidates. A 'MATCHED' status with a high score (>0.9) indicates high confidence. Check the 'changes' array to see what corrections were made.

You need to search for addresses within a specific geographic area using structured criteria.

Use the GET /addresses/search endpoint with query parameters: 'canton' (2-letter code like ZH, BE, VD), 'zip4' (4-digit postal code), 'localityName', or 'municipalityName'. You can combine multiple parameters for precise filtering. All criteria are combined with AND logic. Add 'limit' to control the number of results returned.

You need to understand the data source for compliance or quality assurance purposes.

HelvAddress uses official Swiss federal data sources: 1) The Federal Register of Buildings and Dwellings (RBD/GWR) from the Federal Statistical Office, 2) The official Swiss locality register from swisstopo. This data is used under the terms of free geodata from swisstopo. See our Legal Notice for full data source attribution.

You want to know how current the address data is and when updates are applied.

Our address database is updated regularly to reflect changes in the official Swiss registers. Major updates are applied monthly, with critical corrections applied more frequently. The API response includes a 'dataVersion' field indicating the data version used. We maintain synchronization with official sources to ensure accuracy.

You need to confirm that the API provides complete coverage for your use case across Switzerland.

Yes, HelvAddress covers all 26 Swiss cantons and includes addresses from the complete Federal Register of Buildings and Dwellings. This includes residential, commercial, and public buildings with official entrance addresses. The database contains millions of addresses across all Swiss municipalities and postal codes.

Your search queries are returning empty results even though you expect matches to exist.

Common causes: 1) Spelling errors in the search query - try the autocomplete endpoint which is more forgiving, 2) Using filters that are too restrictive - try removing some filters, 3) The address may not exist in the official register, 4) For normalize endpoint, ensure the input is a complete enough address. Check that your query includes at least a street name or postal code.

You're experiencing slow response times from the API affecting your application's user experience.

To improve performance: 1) Use the autocomplete endpoint with a low limit (5-10) for real-time search, 2) Implement client-side debouncing (200-300ms) to reduce unnecessary calls, 3) Cache responses for repeated queries, 4) Ensure your server has good network connectivity to our API servers, 5) Consider using our search endpoint with specific filters instead of broad autocomplete queries.

You're receiving error responses and need to understand what they mean and how to handle them.

Common HTTP status codes: 400 Bad Request (invalid parameters - check the 'validationErrors' field), 401 Unauthorized (invalid or expired token - re-authenticate), 403 Forbidden (insufficient permissions), 404 Not Found (address ID doesn't exist), 422 Unprocessable Entity (address couldn't be parsed), 429 Too Many Requests (rate limited - wait and retry). All errors include a JSON body with 'message' explaining the issue.

You're getting Cross-Origin Resource Sharing (CORS) errors when making API calls from a web browser.

For security reasons, direct browser-to-API calls require CORS headers. Solutions: 1) Make API calls from your backend server instead of the browser (recommended for security), 2) Use a proxy endpoint on your server that forwards requests to our API. Note: Never expose your client_secret in browser-side code as it can be extracted by users.

You want to integrate the API quickly using a pre-built library for your programming language.

We provide official API documentation with OpenAPI/Swagger specifications that can be used to generate client libraries for any language. You can use tools like OpenAPI Generator to create type-safe clients. Our REST API is simple enough to integrate directly using standard HTTP libraries in any programming language.

You want to integrate address validation into an existing e-commerce or CMS platform.

Yes, HelvAddress can be integrated with any platform that supports custom API calls or webhooks. For e-commerce platforms, you can integrate at checkout to validate shipping addresses. Implementation typically involves: 1) A backend service that calls our API, 2) Frontend JavaScript that displays suggestions from the autocomplete endpoint. Contact us for platform-specific guidance.

Switzerland has four official languages and you need to handle address data in different languages.

Swiss addresses are stored in their official local language form (German, French, Italian, or Romansh depending on the region). The API returns addresses in their official registered form. Street names and locality names are not translated. Your application should display addresses as returned by the API to ensure accuracy with official postal standards.