SpotSense Getting Started: API Keys & First Request (2026)

Getting started overview

Integrating SpotSense APIs involves a series of steps designed to enable developers to quickly access its geolocation and mapping services. The process begins with account creation and the generation of an API key, which is essential for authenticating all requests. SpotSense provides a unified API for various services, including geocoding, reverse geocoding, and address autocomplete, accessible via RESTful endpoints. The platform emphasizes developer experience, offering detailed documentation and SDKs for common programming languages to facilitate rapid integration.

This guide provides a structured approach to getting started with SpotSense, covering account setup, API key management, and executing your first API call. It focuses on practical steps to ensure a smooth initial integration, allowing developers to quickly move from setup to leveraging SpotSense's capabilities in their applications.

Quick Reference Steps

The following table outlines the key steps to get started with SpotSense:

Create an account and get keys

Access to SpotSense APIs is contingent on having an active account and valid API keys. These keys serve as authentication credentials, securely identifying your application with each request and ensuring proper usage tracking against your plan limits.

Account Registration

To begin, navigate to the SpotSense homepage and initiate the registration process. This typically involves providing an email address, setting a password, and agreeing to the terms of service. SpotSense offers a free tier that includes 5,000 requests per month, which is suitable for initial development and testing.

API Key Generation and Management

1. Access Dashboard: After successful registration and login, you will be directed to the SpotSense developer dashboard.
2. Navigate to API Keys: Within the dashboard, locate the section dedicated to 'API Keys' or 'Credentials'. The exact navigation may vary slightly but is typically prominent for developer access.
3. Generate New Key: If no key exists, or if you wish to create a project-specific key, select the option to 'Generate New API Key'. You may be prompted to provide a name or description for the key to help with organization, especially if managing multiple projects.
4. Key Security: Your API key is a sensitive credential. It should be treated like a password and kept confidential. Avoid hardcoding it directly into client-side code exposed in browsers or mobile applications. Instead, use environment variables or a secure server-side proxy to manage and inject the key into your requests. For client-side applications, consider using a server-side component to make requests to SpotSense on behalf of the client, where the API key can be securely stored.
5. Review Usage: The dashboard also provides tools to monitor your API usage, helping you track request volumes and manage your budget, particularly when operating under the free tier or a paid plan.

Your first request

With an API key in hand, you are ready to make your first request to the SpotSense API. This example will use the Geocoding API, which converts a human-readable address into geographic coordinates (latitude and longitude). The request can be made directly using cURL, which is a command-line tool for transferring data with URLs, or using one of the SpotSense SDKs.

Geocoding API Endpoint

The primary endpoint for the Geocoding API is typically structured as follows:

GET https://api.spotsense.ai/v1/geocode?address={address}&api_key={your_api_key}

Replace {address} with the address you wish to geocode (URL-encoded) and {your_api_key} with the API key obtained from your dashboard.

Example Request with cURL

To make a request using cURL, open your terminal or command prompt and execute the following command. Remember to replace YOUR_API_KEY with your actual SpotSense API key and URL-encode the address.

curl -X GET \
  "https://api.spotsense.ai/v1/geocode?address=1600+Amphitheatre+Parkway%2C+Mountain+View%2C+CA&api_key=YOUR_API_KEY"

A successful response will typically return a JSON object containing the geocoded location data, including latitude, longitude, and other relevant address components.

{
  "status": "success",
  "results": [
    {
      "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "geometry": {
        "lat": 37.4224764,
        "lng": -122.0842499
      },
      "address_components": [
        { "long_name": "1600", "short_name": "1600", "types": ["street_number"] },
        { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": ["route"] },
        { "long_name": "Mountain View", "short_name": "Mountain View", "types": ["locality", "political"] },
        { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "types": ["administrative_area_level_2", "political"] },
        { "long_name": "California", "short_name": "CA", "types": ["administrative_area_level_1", "political"] },
        { "long_name": "United States", "short_name": "US", "types": ["country", "political"] },
        { "long_name": "94043", "short_name": "94043", "types": ["postal_code"] }
      ]
    }
  ]
}

Example Request with Python SDK

SpotSense offers SDKs to simplify interaction with its API. For Python, the process involves installing the SDK and then using it to make the request.

1. Install the SDK:

pip install spotsense-python

2. Make the request:

import spotsense

spotsense.api_key = "YOUR_API_KEY"

def geocode_address(address):
    try:
        response = spotsense.Geocoding.geocode(address=address)
        if response and response.get('status') == 'success':
            for result in response.get('results', []):
                print(f"Formatted Address: {result['formatted_address']}")
                print(f"Latitude: {result['geometry']['lat']}, Longitude: {result['geometry']['lng']}")
        else:
            print(f"Error geocoding address: {response.get('message', 'Unknown error')}")
    except spotsense.exceptions.SpotSenseAPIError as e:
        print(f"API Error: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

geocode_address("1600 Amphitheatre Parkway, Mountain View, CA")

This Python example demonstrates how to set your API key and use the geocode method to query the Geocoding API. The SDK handles the underlying HTTP request and JSON parsing, returning a structured object.

Common next steps

After successfully making your first request, consider these common next steps to further integrate SpotSense into your application and explore its full capabilities:

1. Explore Other APIs: SpotSense offers several other APIs beyond basic geocoding, including Reverse Geocoding (coordinates to addresses), Autocomplete (predictive address input), and Places API (point of interest search). Review the API reference documentation to understand their functionalities and how they can enhance your application.
2. Implement Advanced Features: Look into features like filtering results by country, specifying result languages, or handling rate limits. The documentation provides details on these advanced parameters and best practices. Developers often need to consider rate limiting when scaling their applications.
3. Error Handling: Implement robust error handling in your application to gracefully manage API access issues, invalid parameters, or server-side problems. The SpotSense API returns specific error codes and messages to help diagnose issues.
4. Secure API Keys: Revisit your API key management strategy. For production applications, ensure API keys are not hardcoded and are accessed securely, potentially using server-side environments or secure token mechanisms to prevent unauthorized access. This aligns with general API security best practices.
5. Monitor Usage: Regularly check your SpotSense dashboard to monitor API usage against your plan limits. This helps prevent unexpected service interruptions or overage charges.
6. Explore SDKs: If you used cURL for your first request, consider migrating to one of the official SDKs for your preferred language (e.g., Node.js, Java, PHP, Ruby, Go). SDKs typically simplify API interaction, handling authentication, request formatting, and response parsing.

Troubleshooting the first call

Encountering issues during your first API call is a common part of the development process. Here are some typical problems and their solutions when working with SpotSense:

• Invalid API Key:
  • Symptom: An error message indicating an invalid API key, unauthorized access, or a 401 Unauthorized HTTP status code.
  • Solution: Double-check that you have copied the API key correctly from your SpotSense dashboard. Ensure there are no leading or trailing spaces. If you have multiple keys, confirm you are using the correct one for the intended environment.
• Missing API Key:
  • Symptom: An error message stating the API key is missing or a 400 Bad Request with a message about missing parameters.
  • Solution: Verify that the api_key parameter is included in your request URL or headers, as specified by the SpotSense API documentation.
• Incorrect Endpoint or Parameters:
  • Symptom: A 404 Not Found error or an unexpected response structure.
  • Solution: Compare your request URL and parameters precisely with the SpotSense API Reference. Pay close attention to capitalization, parameter names, and required fields. Ensure the address parameter is URL-encoded, especially for addresses containing spaces or special characters.
• Network Issues:
  • Symptom: Request timeouts, connection refused errors, or general network connectivity problems.
  • Solution: Check your internet connection. If using a corporate network, ensure there are no firewalls or proxy settings blocking access to api.spotsense.ai. Try the cURL command from a different network or a simple browser request to isolate the issue.
• Rate Limit Exceeded:
  • Symptom: A 429 Too Many Requests HTTP status code.
  • Solution: You have exceeded the number of requests allowed within a specific timeframe (e.g., your free tier limit of 5,000 requests/month). Wait for the rate limit to reset, or consider upgrading your SpotSense plan to accommodate higher request volumes. Implement client-side rate limiting or exponential backoff in your application to manage request frequency.
• Invalid JSON Response:
  • Symptom: Your application fails to parse the API response, or the response is not valid JSON.
  • Solution: While rare with well-behaved APIs, ensure your code is correctly handling the response as JSON. Use a JSON validator tool if you suspect the raw response is malformed. If the response is an HTML error page, it often indicates a misconfigured web server or proxy rather than an API error.
• SDK Specific Errors:
  • Symptom: Errors originating from the SpotSense SDK (e.g., SpotSenseAPIError in Python).
  • Solution: Consult the specific SDK documentation for details on error handling and common issues. Ensure your SDK version is up to date.