Getting started overview

Getting started with openSenseMap involves understanding its core components: the senseBox, which is a physical sensor station, and the openSenseMap platform, which collects, visualizes, and provides access to the data from these stations. The platform is designed for community-contributed environmental measurements and offers an open API for both data retrieval and contribution. This guide focuses on the steps required to access and interact with the openSenseMap API, specifically for retrieving existing sensor data.

The openSenseMap API follows RESTful principles, using standard HTTP methods to interact with resources like senseBoxes, sensors, and measurements. Data is typically returned in JSON format, making it compatible with a wide range of programming languages and tools. Unlike some APIs that require an API key for all operations, public data retrieval from openSenseMap does not necessitate specific authentication. This design choice supports its mission as an open-source citizen science platform, allowing broad access to environmental data for research and public awareness. For operations that modify data, such as registering a new senseBox or sending sensor data, specific authentication mechanisms like a senseBox ID and an access token are required to ensure data integrity and user accountability.

To begin, users typically navigate to the openSenseMap homepage to explore existing data or register a new senseBox. The platform's documentation portal provides comprehensive guides for both hardware setup and API usage. Developers can interact with the API directly using tools like curl, or programmatically using client libraries in languages such as Python or JavaScript. Understanding the structure of the API endpoints and the expected request/response formats is crucial for successful integration.

The openSenseMap platform also supports various data visualization tools, allowing users to view sensor data on interactive maps and charts. This visual interface can be a valuable starting point for identifying specific senseBoxes or geographic areas of interest before making programmatic API calls. The platform's commitment to open data is a foundational aspect, aligning with broader initiatives for open science and environmental monitoring, as detailed by organizations like the W3C Open Data Community Group.

Create an account and get keys

For retrieving public sensor data from openSenseMap, an account and API keys are generally not required. The platform is built on an open data philosophy, meaning much of the collected environmental data is publicly accessible without authentication. This simplifies the process for developers who only need to read existing data. However, if you plan to contribute data, register a new senseBox, or manage your own devices, creating an account is necessary.

Account Creation Steps:

  1. Navigate to the Signup Page: Go to the openSenseMap main website and look for a "Login" or "Register" link, typically found in the navigation bar.
  2. Provide Information: You will generally be asked for an email address and a password. Some platforms may also request a username or other basic profile information.
  3. Email Verification: After submitting your details, openSenseMap will likely send a verification email to the address you provided. Follow the instructions in the email to activate your account. This is a common security practice to ensure the email address is valid and owned by you.
  4. Login: Once your account is verified, you can log in to the openSenseMap dashboard.

Understanding API Keys and Authentication for Write Operations:

While public read access doesn't require keys, write operations (e.g., uploading new sensor data) do. Instead of a single API key, openSenseMap uses a combination of a senseBox ID and an Access Token for authenticating data uploads from specific senseBoxes. These identifiers are generated when you register a new senseBox through your account.

When you register a new senseBox on the platform, the system assigns it a unique senseBox ID. You will also be provided with an Access Token specific to that senseBox. This token acts as the authentication credential for that particular device to send data to the openSenseMap API. It's crucial to keep this Access Token secure, as it grants permission to write data for your senseBox.

To obtain a senseBox ID and Access Token (for data contribution):

  1. Log in to your openSenseMap account.
  2. Navigate to the section for adding or managing senseBoxes.
  3. Follow the prompts to register a new senseBox. During this process, the platform will generate and display the senseBox ID and Access Token for your new device. Make sure to record these securely. The official documentation provides detailed instructions on this process.

Your first request

Making your first request to the openSenseMap API involves querying public sensor data. Since no authentication is required for reading public data, you can directly use the API endpoints. This example demonstrates how to retrieve the latest measurements from a specific senseBox using curl, a command-line tool for making HTTP requests. The openSenseMap API reference provides a comprehensive list of available endpoints and parameters for querying data.

API Endpoint Structure

The base URL for the openSenseMap API is https://api.opensensemap.org. Endpoints are typically structured to allow access to specific resources like senseBoxes, sensors, and their measurements.

Example: Get Latest Measurements for a senseBox

To retrieve the latest measurements from a specific senseBox, you can use the /boxes/{senseBoxId}/data endpoint. You'll need to replace {senseBoxId} with the actual ID of a senseBox. You can find senseBox IDs by browsing the openSenseMap map and clicking on individual senseBoxes.

curl -X GET "https://api.opensensemap.org/boxes/652f2081977717001bb0a16b/data" \ 
     -H "accept: application/json"

In this example, 652f2081977717001bb0a16b is a placeholder for a specific senseBox ID. When you execute this curl command, the API will return a JSON object containing the latest measurements for all sensors associated with that senseBox. The response will include details such as the sensor ID, measurement value, and timestamp.

Example Response (abbreviated):

[
  {
    "sensorId": "652f2081977717001bb0a16e",
    "value": "22.5",
    "createdAt": "2024-05-29T10:00:00.000Z",
    "unit": "°C",
    "sensorType": "BME280_temperature"
  },
  {
    "sensorId": "652f2081977717001bb0a16f",
    "value": "60.2",
    "createdAt": "2024-05-29T10:00:00.000Z",
    "unit": "%",
    "sensorType": "BME280_humidity"
  }
]

This response format provides an array of objects, where each object represents a measurement from a specific sensor on the senseBox. Key fields include sensorId, value, createdAt (timestamp), unit, and sensorType.

Using a Web Browser

You can also test simple GET requests directly in your web browser by navigating to the API endpoint URL, for example: https://api.opensensemap.org/boxes/652f2081977717001bb0a16b/data. The browser will display the raw JSON response.

Common next steps

After successfully making your first API request to openSenseMap, several common next steps can enhance your interaction with the platform and its data:

  • Explore the API Reference: Dive deeper into the comprehensive openSenseMap API documentation. This reference details all available endpoints, query parameters, and response structures, allowing you to fetch historical data, filter by sensor type, or query multiple senseBoxes simultaneously. Understanding these options will enable more complex and targeted data retrieval.
  • Integrate with a Programming Language: Move beyond curl and integrate the API into your preferred programming language (e.g., Python, JavaScript, Ruby). Libraries like Python's requests or JavaScript's fetch API can simplify making HTTP requests, parsing JSON responses, and handling potential errors. This allows for automation and building custom applications around openSenseMap data.
  • Data Visualization: Once you can retrieve data programmatically, consider visualizing it. You can use libraries such as Matplotlib or Plotly in Python, or D3.js in JavaScript, to create custom charts, graphs, and maps that represent the environmental data in an insightful way. This step is particularly relevant for citizen science projects or educational purposes.
  • Contribute Data: If you have a senseBox or are building one, learn how to send your own sensor data to the openSenseMap platform. This involves registering your senseBox, obtaining its ID and access token, and then making authenticated POST requests to the /boxes/{senseBoxId}/data endpoint. The openSenseMap guides provide specific examples for different senseBox configurations.
  • Error Handling: Implement robust error handling in your code. The API will return specific HTTP status codes (e.g., 400 for bad request, 404 for not found, 500 for server errors) and often include descriptive error messages in the JSON response. Properly handling these will make your application more resilient.
  • Community Engagement: Engage with the openSenseMap community. This can involve participating in forums, reporting issues, or contributing to the open-source codebase. The community can be a valuable resource for troubleshooting and learning best practices.
  • Explore Advanced Features: Investigate advanced API features such as filtering data by time ranges, geographical bounding boxes, or specific sensor types. These capabilities allow for more granular control over the data you retrieve and can be essential for specific research questions or application requirements.

Troubleshooting the first call

When making your first API call to openSenseMap, you might encounter issues. Here are common problems and their solutions:

Common Issues and Solutions:

Problem What to Check Where to Check
404 Not Found
  • Incorrect endpoint URL.
  • Invalid senseBoxId.
No Data Returned (Empty Array)
  • The specified senseBox might not have recent data.
  • Incorrect query parameters (if used).
  • Check the senseBox on the openSenseMap website to see if it's active and reporting data.
  • Review your query parameters (e.g., time range) for accuracy against the API reference.
Network Error / Connection Refused
  • No internet connection.
  • Firewall blocking the request.
  • API server temporarily down.
  • Verify your internet connection.
  • Temporarily disable your firewall or check its settings.
  • Check the openSenseMap status page or community forums for service announcements.
JSON Parsing Errors
  • Response is not valid JSON.
  • Incorrect content type header.
  • Ensure your request includes -H "accept: application/json" if using curl.
  • Use a JSON validator tool to inspect the raw response if you suspect malformed JSON.
Incorrect Data Values or Types
  • Misunderstanding of response structure.
  • Sensor data units or types are not as expected.
  • Refer to the specific sensor type definitions in the openSenseMap API documentation.
  • Examine the unit and sensorType fields in the JSON response carefully.

General Troubleshooting Tips:

  • Start Simple: Begin with the most basic request (like fetching all data for a known senseBox ID) before adding complex parameters.
  • Check Documentation: The openSenseMap documentation is the primary source of truth for API behavior and endpoint specifics.
  • Use Developer Tools: If making requests from a web browser, use your browser's developer console (Network tab) to inspect the request and response details, including headers and status codes.
  • Community Support: If you're still stuck, consider reaching out to the openSenseMap community forums or support channels. Provide clear details of your request, the error message, and what you've already tried.