Use public API data in a simulation
Fetch credential-free public data at run start, map it into typed simulation fields, and let those values change model behavior.
Add a Public API source when a run should begin from published observations, reference data, schedules, prices, weather, or another external dataset that is available without private credentials.
Map the returned values into fields the model actually uses. If the data never changes routing, timing, capacity, state, or another simulated outcome, it is reference material rather than a simulation input.
The model uses mapped API values as ordinary typed message fields.
- 1. FetchPublic API
GET a credential-free HTTPS endpoint when the run starts.
- 2. ShapeDataFlow mapping
Select, rename, and cast response fields into the model contract.
- 3. InjectRun-start events
Materialize each mapped record as a scheduled simulation message.
- 4. UseModel behavior
Route, queue, or process the entity using the values returned by the API.
The request is sent from your browser. Use an HTTPS endpoint that accepts GET requests without cookies, authorization headers, API keys, or a request body. The provider must allow cross-origin browser requests, and the response must stay below 16 MiB.
Do not put secrets into a URL. Use an authenticated integration or server-side connector for private APIs.
- HTTPS only.
- GET only.
- No browser credentials or authentication headers.
- The endpoint must permit cross-origin browser access.
- JSON, CSV, and NDJSON can be parsed as input records.
Many APIs wrap records inside metadata or use field names that do not match your simulation entity. Select the response path first, then rename fields, convert types, and reject invalid records before injection.
Choose immediate injection when the records define the starting state. Use timestamp-based injection when each record represents an event that should occur later in simulated time.
The runnable World Bank example uses Singapore population data to change a simulation route. The explorable below goes further: one World Bank request fetches population, GDP per person, net migration, and freshwater withdrawals for the same country.
Keep an input on World Bank to use the fetched value, or switch it to What-if and change the assumption yourself. Water capacity and food/logistics capacity are scenario controls rather than fetched facts, so you can test whether added capacity keeps up with extra demand.
The results are deliberately simple what-if estimates, not forecasts. Their purpose is to show how real external data can become a baseline and how changed assumptions propagate through a model immediately.
- Population, total: SP.POP.TOTL.
- GDP per capita: NY.GDP.PCAP.CD.
- Net migration: SM.POP.NETM.
- Freshwater withdrawals, total: ER.H2O.FWTL.K3.
- Scenario controls: migration, GDP per person, water use per person, water capacity, and food/logistics capacity.
Advanced details: toy scenario arithmetic
Scenario population is the fetched population plus the selected net-migration input. This intentionally leaves births, deaths, policy feedback, and behavioral responses out of the estimate.
The GDP estimate multiplies scenario population by the selected GDP-per-person value. Water pressure compares the population and per-person water-demand change with the selected water-capacity change. The food/logistics index compares population change with the selected capacity change.
pressure index = 100 × demand factor / capacity factor
A public endpoint can be unavailable, change its response schema, revise historical values, or return newer data later. That is useful when a study intentionally wants current external data, but it weakens exact replay if the input is fetched again in the future.
For a study that must reproduce the exact same inputs, save the dataset as a fixed file and import that file instead of depending on a live request. Record the provider, query, retrieval date, and any transformation used to create the model input.
Public access also does not imply unrestricted reuse. Check the provider's data licence and attribution rules before publishing or redistributing results. World Bank open datasets are generally published under CC BY 4.0 unless the dataset or indicator states otherwise.