HelloSalut Getting Started: Quickstart Guide (2026)

Getting started overview

Integrating HelloSalut's geospatial APIs involves a few key steps to ensure you can quickly begin utilizing its geocoding, reverse geocoding, timezone, and IP geolocation services. This guide focuses on the essential process from account setup to making your first successful API call. HelloSalut provides a comprehensive documentation portal with detailed API references and code examples to support developers through the integration process.

Before making API calls, you will need to create an account on the HelloSalut platform and obtain an API key. This key authenticates your requests and links them to your usage plan. HelloSalut offers a free tier that includes 5,000 requests per month, allowing developers to test and build small applications without initial cost.

The core of HelloSalut's offering is its RESTful API, which means interactions are based on standard HTTP methods (GET, POST) and data is typically exchanged in JSON format. This approach is common in web APIs, facilitating integration across various programming languages and environments (Mozilla Developer Network REST definition).

Here’s a quick reference table outlining the initial steps:

Create an account and get keys

To begin using HelloSalut, your first step is to create an account. Navigate to the HelloSalut homepage and follow the registration process. This typically involves providing an email address, setting a password, and agreeing to the terms of service. Once registered, you will gain access to your personal dashboard.

Upon successful account creation and login, your API key will be prominently displayed within your dashboard. This key is a unique alphanumeric string that serves as your authentication token for all API requests. It is crucial to keep your API key confidential to prevent unauthorized usage of your account. Do not embed it directly into client-side code that could be publicly exposed.

HelloSalut offers a free tier providing 5,000 requests per month. This tier is automatically applied upon account creation, allowing immediate access to the API for testing and development purposes. If your needs exceed the free tier, you can upgrade to a paid plan, with options starting at 9 EUR/month for 50,000 requests.

For security best practices, consider using environment variables or a secrets management service to store and access your API key, especially in production environments. This approach helps prevent your key from being hardcoded into your application's source code.

Your first request

Once you have your API key, you can make your first API request. This example demonstrates a basic geocoding request, converting a human-readable address into geographical coordinates (latitude and longitude). HelloSalut's Geocoding API is a core product, designed for straightforward address lookup.

The base URL for the Geocoding API is https://api.hellosalut.com/v1/geocode. You will need to append query parameters, including the address you wish to geocode and your API key.

Example: Geocoding an address (Python)

This Python example uses the requests library to make a GET request to the Geocoding API. Ensure you replace YOUR_API_KEY with your actual API key and YOUR_ADDRESS with the address you want to geocode.

import requests
import json

API_KEY = "YOUR_API_KEY"
ADDRESS = "1600 Amphitheatre Parkway, Mountain View, CA"

url = f"https://api.hellosalut.com/v1/geocode?address={ADDRESS}&key={API_KEY}"

try:
    response = requests.get(url)
    response.raise_for_status()  # Raise an exception for HTTP errors
    data = response.json()

    if data and data.get("status") == "success":
        results = data.get("results", [])
        if results:
            first_result = results[0]
            latitude = first_result.get("geometry", {}).get("lat")
            longitude = first_result.get("geometry", {}).get("lng")
            print(f"Address: {ADDRESS}")
            print(f"Latitude: {latitude}, Longitude: {longitude}")
        else:
            print("No geocoding results found.")
    else:
        print(f"API Error: {data.get('message', 'Unknown error')}")

except requests.exceptions.HTTPError as http_err:
    print(f"HTTP error occurred: {http_err}")
except requests.exceptions.ConnectionError as conn_err:
    print(f"Connection error occurred: {conn_err}")
except requests.exceptions.Timeout as timeout_err:
    print(f"Timeout error occurred: {timeout_err}")
except requests.exceptions.RequestException as req_err:
    print(f"An unexpected error occurred: {req_err}")
except json.JSONDecodeError:
    print("Failed to decode JSON response.")

Example: Geocoding an address (JavaScript with Fetch)

This JavaScript example uses the browser's native fetch API to perform the same geocoding request. This code would typically run in a Node.js environment or within a secure server-side context to protect your API key.

const API_KEY = "YOUR_API_KEY";
const ADDRESS = "Eiffel Tower, Paris, France";

const url = `https://api.hellosalut.com/v1/geocode?address=${encodeURIComponent(ADDRESS)}&key=${API_KEY}`;

fetch(url)
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    if (data && data.status === "success") {
      const results = data.results;
      if (results && results.length > 0) {
        const firstResult = results[0];
        const latitude = firstResult.geometry.lat;
        const longitude = firstResult.geometry.lng;
        console.log(`Address: ${ADDRESS}`);
        console.log(`Latitude: ${latitude}, Longitude: ${longitude}`);
      } else {
        console.log("No geocoding results found.");
      }
    } else {
      console.error(`API Error: ${data.message || 'Unknown error'}`);
    }
  })
  .catch(error => {
    console.error('There was a problem with the fetch operation:', error);
  });

After executing these examples, you should see the latitude and longitude coordinates printed to your console. This indicates a successful connection to the HelloSalut API and a valid response.

Common next steps

With your first successful API call, you can now explore more advanced features and integrate HelloSalut further into your applications. Here are some common next steps:

• Explore other APIs: HelloSalut offers Reverse Geocoding, Timezone, and IP Geolocation APIs. Investigate how these can enhance your application's location-based functionalities. For instance, Reverse Geocoding can convert coordinates back into human-readable addresses.
• Use SDKs: While direct HTTP requests are feasible, HelloSalut provides official SDKs for JavaScript, Python, PHP, and Ruby. Using an SDK can simplify API interactions, handling request formatting, error handling, and authentication boilerplate.
• Implement error handling: Robust applications require comprehensive error handling. Refer to the HelloSalut API reference for a list of possible error codes and messages to implement appropriate responses in your code.
• Monitor usage: Regularly check your dashboard for API usage statistics. This helps you stay within your plan limits and understand your application's demand for geospatial data.
• Secure your API key: Ensure your API key is not exposed in client-side code or public repositories. For web applications, consider proxying requests through your backend server to add an extra layer of security.
• Review pricing and scaling: As your application grows, you may need to upgrade your HelloSalut plan. Familiarize yourself with the available pricing tiers to plan for scaling.
• Learn about rate limits: Understand the rate limits applicable to your chosen plan to avoid unexpected service interruptions. The documentation provides details on these limitations.
• Explore advanced features: Look into features like language localization for results, result filtering, or batch geocoding if your use case requires them.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps and common problems:

• Invalid API Key: Double-check that you have copied your API key correctly from your HelloSalut dashboard. An incorrect key will result in an authentication error (e.g., HTTP 401 Unauthorized or a specific API error message indicating an invalid key).
• Missing Parameters: Ensure all required parameters, such as the address for geocoding, are included in your request URL. Missing parameters often lead to HTTP 400 Bad Request errors or specific API error messages.
• Network Issues: Verify your internet connection. If you are behind a firewall or proxy, ensure it allows outgoing requests to api.hellosalut.com. Connection errors (e.g., requests.exceptions.ConnectionError in Python) indicate network problems.
• Rate Limit Exceeded: While less likely on a first call, if you are rapidly testing, you might hit the rate limit of your free tier. The API will typically return an HTTP 429 Too Many Requests status code. Wait a short period before retrying.
• Incorrect URL Endpoint: Confirm that you are using the correct base URL and endpoint for the specific API you are calling (e.g., /v1/geocode for geocoding). Refer to the HelloSalut API reference for exact endpoints.
• JSON Parsing Errors: If the API returns a response that isn't valid JSON, your code's JSON parser will fail. This can happen if the API returns an HTML error page (e.g., a server error) instead of a JSON response. Check the raw response content if you encounter such an error.
• Typos in Address: While geocoding is robust, extremely malformed or non-existent addresses might not yield results. Try a well-known address first to confirm basic functionality.
• Check API Status Page: In rare cases, the HelloSalut service might be experiencing an outage. Check the HelloSalut website or their social media for any service status updates.
• Consult Documentation: The HelloSalut documentation provides detailed error codes and messages, which can help pinpoint the exact cause of a problem.