External API Integration
Purpose
The Virtual Rodent project integrates the Open-Meteo API to allow researchers to import real-world environmental conditions into an experiment.
The feature is exposed through the Environment Import interface.
Instead of requiring researchers to manually configure every environmental value, the application can retrieve environmental data for a selected location, date and time and convert applicable values into configurable simulation settings.
The integration currently supports environmental information used for:
- light;
- ambient sound; and
- temperature data.
Temperature is retrieved and stored so that it can be used by the simulation's temperature support.
The integration does not generate odour settings because the external weather data does not provide an appropriate basis for experimental odour configuration.
External API
The external service used by the project is:
Open-Meteo
Open-Meteo provides weather and environmental data through HTTP APIs.
The integration uses environmental variables such as:
- temperature at 2 metres;
- cloud cover;
- precipitation;
- wind speed;
- weather code;
- day/night state; and
- shortwave solar radiation.
The project also uses Open-Meteo's geocoding service to resolve a researcher-entered location into coordinates and location metadata.
Integration architecture
The Godot interface does not communicate directly with Open-Meteo.
External API access is handled through the project's Python backend.
The integration boundary is:
Researcher
|
v
Environment Import UI
|
v
Virtual Rodent internal API
backend/app.py
|
v
Environment service
backend/environment_service.py
|
v
Open-Meteo API
|
v
Normalised environmental data
|
v
Generated experiment settings
This design prevents the Godot interface from depending directly on Open-Meteo's response structure.
It also keeps provider-specific networking and data conversion separate from the simulation and user interface.
Environment Import workflow
The researcher begins the workflow from the Environment Import tab.
The workflow is:
Enter location
|
v
Select date and time
|
v
Fetch Environment
|
v
Resolve location
|
v
Retrieve environmental data
|
v
Generate suggested settings
|
v
Review and edit
|
v
Apply to Experiment
Fetching environmental data does not immediately modify the active experiment.
The researcher first receives a preview of the retrieved conditions and generated settings.
The generated settings can then be reviewed or changed before the researcher selects Apply to Experiment.
This prevents an external API response from silently overwriting an experiment configuration.
Location resolution
Researchers provide a human-readable location rather than having to manually enter latitude and longitude coordinates.
The location is resolved using the Open-Meteo Geocoding API.
The geocoding request converts a location such as:
Johannesburg, South Africa
into information such as:
- location name;
- administrative region;
- country;
- latitude;
- longitude; and
- timezone.
The resolved coordinates are then used for the environmental data request.
If the location cannot be resolved, the application displays an error and the active experiment remains unchanged.
Environmental data retrieval
After the location has been resolved, the environment service retrieves conditions for the selected date and time.
The integration can use the appropriate Open-Meteo weather dataset depending on the requested date.
The project requests only environmental variables required by the feature.
The main values are:
temperature_2m
cloud_cover
precipitation
weather_code
wind_speed_10m
is_day
shortwave_radiation
The Open-Meteo documentation defines cloud cover as a percentage, wind speed at 10 metres as a standard wind measurement, and shortwave radiation as solar radiation measured in watts per square metre.
The external values are converted into a project-owned data structure before being returned to the rest of the application.
Data normalisation
Open-Meteo-specific response data is kept inside the environment service.
The rest of Virtual Rodent uses normalised names such as:
temperature_c
cloud_cover_percent
precipitation_mm
wind_speed_kmh
weather_code
is_day
shortwave_radiation_wm2
The boundary is therefore:
Open-Meteo response
|
v
Provider-specific parsing
|
v
Virtual Rodent environment structure
|
v
UI and experiment configuration
This means that the rest of the project does not need to understand the structure of the external API response.
It also makes it easier to replace or extend the provider integration in future.
Light generation
Environmental data is used to generate a suggested light configuration.
The light calculation uses environmental information such as:
- whether the selected time is during the day;
- shortwave solar radiation; and
- cloud cover.
At night, the imported environmental light can be inactive or have zero generated intensity.
During daylight, solar radiation and cloud cover are used to calculate a suggested light value within the range supported by the Virtual Rodent experiment configuration.
The generated value is a simulation preset heuristic.
It is not intended to claim that a weather measurement corresponds to an experimentally calibrated lux value.
The researcher can change the generated light setting before applying it.
Ambient sound generation
Precipitation and wind are used to generate an ambient sound suggestion.
The general mapping is:
Low wind + no rain
|
v
No weather ambience
Rain
|
v
Rain ambience
Strong wind
|
v
Wind ambience
Rain + strong wind
|
v
Combined weather ambience
The generated sound gain is constrained to the range supported by the application.
As with light generation, these mappings are application preset rules rather than scientific measurements of real-world sound pressure.
The researcher can edit the generated sound setting before applying it.
Temperature integration
The API retrieves the environmental temperature using Open-Meteo's 2 metre temperature value.
The temperature is displayed as part of the imported environmental conditions and stored with the experiment.
This separates external data retrieval from the simulation behaviour that consumes the temperature value.
The environment integration is therefore responsible for obtaining and preserving the real-world condition, while temperature-related simulation logic can use the stored value independently.
Applying imported settings
Selecting Apply to Experiment copies the accepted environment values into the active experiment configuration.
Environment Import and Setup operate on the same logical experiment.
The relationship is:
Manual Setup ----------------+
|
v
Active Experiment
^
|
Environment Import ----------+
This means that settings generated through Environment Import can also be viewed and adjusted through the normal experiment configuration workflow.
Environment Import must not overwrite unrelated experimental stimuli.
For example, an intentionally configured experimental light should remain separate from an imported ambient environment light.
Odour configuration is not changed by the environment integration.
Reproducibility
Reproducibility is an important part of the integration.
The external API is used when the researcher imports the environment.
After the values have been accepted, the resolved environmental data is stored with the experiment.
The workflow is:
Open-Meteo
|
v
Import conditions
|
v
Researcher accepts settings
|
v
Store resolved values in experiment
|
v
Future run / replay uses stored values
The application does not need to contact Open-Meteo again when a saved experiment is run or replayed.
This prevents a saved experiment from changing because:
- the external API later returns different data;
- the provider changes its models;
- the network is unavailable; or
- the external service is temporarily unavailable.
The saved experiment therefore contains the environmental values that were actually used.
Internal API endpoint
The environment integration is exposed through the project's handwritten Python HTTP API.
The environment preset endpoint is:
POST /api/environment/preset
A request contains the researcher-selected environment information, for example:
{
"location": "Johannesburg, South Africa",
"date": "2026-09-13",
"time": "14:00"
}
The backend then:
- validates the request;
- resolves the location;
- requests environmental data;
- selects the requested time;
- normalises the provider response;
- generates suggested experiment settings; and
- returns the result to the Environment Import interface.
The endpoint follows the existing backend authentication and request-protection behaviour.
Response structure
The internal API returns Virtual Rodent's own response structure rather than forwarding the raw Open-Meteo response.
A simplified response is:
{
"ok": true,
"environment": {
"provider": "open-meteo",
"conditions": {
"temperature_c": 24.0,
"cloud_cover_percent": 35.0,
"precipitation_mm": 0.0,
"wind_speed_kmh": 8.0,
"is_day": true
}
},
"suggested_settings": {
"light": {
"active": true,
"lux": 420.0
},
"sound": {
"active": false,
"gain": 0.0
},
"temperature_c": 24.0
}
}
The exact environmental values depend on the selected location, date and time.
Separation of responsibilities
The integration deliberately separates responsibilities across the system.
Environment Import panel
User input, preview and Apply
backend/app.py
Internal HTTP endpoint and request handling
backend/environment_service.py
Open-Meteo communication
Location resolution
Response normalisation
Preset generation
Experiment configuration
Stores accepted resolved values
Simulation
Uses stored experiment values
This separation prevents external API code from becoming coupled to the simulation kernel.
It also makes the environment logic easier to test independently.
Failure handling
The external service may be unavailable or may not contain data for a requested input.
The integration handles failures without modifying the current experiment.
Possible failures include:
- location not found;
- invalid date or time;
- environmental data unavailable for the requested date;
- missing hourly data;
- network timeout;
- provider unavailable; and
- invalid external response.
The application converts these failures into researcher-readable messages.
Provider exceptions and Python tracebacks are not exposed through the interface.
A failed import leaves the existing experiment configuration unchanged.
External API testing
The external integration is tested without depending on the live Open-Meteo service for automated test success.
Network responses are replaced with controlled test data.
This allows tests to verify the application's behaviour deterministically.
The environment service tests cover areas such as:
- location resolution;
- provider response parsing;
- environmental data normalisation;
- date and time selection;
- light preset generation;
- sound preset generation;
- missing environmental values;
- invalid provider responses; and
- provider failure handling.
Internal API testing
The environment endpoint is also tested through the backend test suite.
The tests verify:
- authentication requirements;
- request protection;
- valid environment requests;
- invalid locations;
- invalid dates;
- invalid times;
- successful normalised responses; and
- safe handling of provider failures.
External network access is mocked during these tests.
This ensures that the automated suite does not fail because of internet availability or changes in the external service.
Environment Import UI testing
The Environment Import interface should be tested separately from the external network layer.
UI tests should verify that:
- the Environment Import panel loads;
- Fetch is available for valid input;
- successful data populates the preview;
- generated settings are displayed;
- generated settings can be edited;
- Apply updates the experiment;
- failed requests display an error;
- failed requests do not modify the experiment; and
- unrelated stimuli remain unchanged.
This follows the project's approach of testing visible interface behaviour separately from service and simulation logic.
Regression testing
The existing Virtual Rodent test suites should be run after changes to the environment integration.
Backend tests can be run from the project root using:
python -m unittest discover -s backend/tests -v
Godot tests should also be rerun, including the existing simulation and UI suites.
For the UI suite:
godot4 --headless --path . --script tests/test_ui.gd
A change to the external API integration must not break existing simulation, recording, replay or experiment configuration behaviour.
Why an external API is used
The external API allows researchers to initialise experiments using environmental conditions associated with a real place and time.
Without the integration, researchers would need to manually determine and enter every environmental value.
The integration therefore provides:
- faster experiment configuration;
- consistent environmental data retrieval;
- location-based presets;
- repeatable conversion rules;
- separation between external data and simulation logic; and
- stored conditions for reproducible experiments.
The external service assists experiment configuration but does not control the simulation directly.
AI Attribution: This document was drafted and edited with AI assistance, including ChatGPT and OpenAI Codex. The team reviewed it against the implemented project.