The Design-Time API introduced in AnyLogic 8.9.7 opened the door to a new way of creating simulation networks programmatically: generating model markup directly during design time using external Python scripts.
Since its release, many AnyLogic users have been exploring how this capability could fit into their existing modeling workflows. One question quickly followed: what kinds of real-world data could now be automatically integrated into AnyLogic?
While the opportunities are numerous, in this blog post, we will look at one practical example: OpenStreetMap data integration. Let’s find out how to generate roads, junctions, and building walls directly on the AnyLogic canvas in seconds.
Contents:
- What is the design-time API?
- The blank canvas problem
- OpenStreetMap data integration
- How the script works
- A real example of OpenStreetMap integration
- What else can the design-time API do?
- FAQs
- The script and a ready-to-run AnyLogic model
What is the design-time API?
In case you missed the introduction of the design-time API in AnyLogic, let’s discover what the concept behind it is.
The design-time API is a Python interface that lets you create and modify AnyLogic model markup without opening the graphical editor. You write a Python script, connect it to a running AnyLogic instance, and the markup appears on the canvas automatically.
It covers the full range of spatial elements across AnyLogic libraries and their elements.
If you can describe spatial structure as data, the design-time API can draw it. That is the key shift: model setup stops being manual work and becomes a repeatable, scriptable process.
The blank canvas problem
Every simulation modeler knows the feeling. You open a new model and stare at an empty canvas. Before you can even place your first car or pedestrian agent, you need to build the spatial environment they will live in, including roads, junctions, walls, and zones. Done manually, even a modest city block can take an hour or two of careful tracing.
For traffic models, you need a road network with correct lane counts and intersections. For pedestrian models, you need walls that define corridors and open spaces. The good news is that both datasets exist and are precisely mapped on OpenStreetMap (OSM). The question is, how do you get them into AnyLogic without drawing everything by hand?
Combine OSM data with the design-time API
The solution is OpenStreetMap data integration.
OSMnx is a Python library developed at the University of Southern California that downloads and processes OpenStreetMap data with just a few lines of code. It returns clean road graphs (nodes = intersections, edges = road segments with lane counts, one-way flags, and geometry) and building footprints. These are exactly the two data sets AnyLogic's Road Traffic and Pedestrian libraries need.
From there, it is a matter of writing a Python script that could bridge the two: OSMnx on one side to download and project the geometry and the AnyLogic design-time API on the other to create Road, RoadJunction, and Wall elements directly on the model canvas. Several sessions with Claude and Gemini can help iterate on the geometry logic, particularly dual carriageway handling and coordinate projection. The result is a working script that can run from the terminal in under a minute.
The blank canvas problem is solved this way thanks to OpenStreetMap data integration. Roads and walls appear automatically on the AnyLogic canvas, ready to be used in your model.
How the script works
The script takes five key arguments: your AnyLogic API token, the model's name, a center point (latitude and longitude), and the size of the area to import. Run it from the terminal, switch to AnyLogic, and the markup will already be there.
Internally, the script runs in three stages:
1. Download OSM data
OSMnx queries the Overpass API and returns a road graph (nodes, edges, lane counts, one-way metadata) and building footprints. Data is cached locally, so repeated runs in the same area are instant.
2. Project and clean geometry
All World Geodetic System 84 coordinates (latitude/longitude) are converted to AnyLogic pixel coordinates. The script uses the Haversine formula to accurately calculate real-world distances in meters on a spherical Earth, then multiplies by PPM (Pixels Per Meter) = 4.0 to get pixel positions, so 1 meter = 4 pixels.
Lane width is derived from object size: LANE_W = 3.5 m × 4 px/m = 14 px per lane.
Note: Match the AnyLogic ruler scale before importing. The script uses PPM = 4.0, meaning 1 meter = 4 pixels. AnyLogic's default ruler is set to 1 meter = 10 pixels. Before running the script, open your model's Space properties and set the ruler to 1 m = 4 px.
To ensure a clean geometry, the following practices are followed:
- Road geometries are simplified and clipped to the bounding box.
- Dual carriageways, which OSM models as two parallel one-way edges, are automatically deduplicated.
- Visually overlapping junctions are merged into one to avoid stacked elements on the canvas.
3. Write markup via the design-time API
With geometry ready, the script opens a transaction against your running AnyLogic instance, creates Road, RoadJunction, and Wall elements on the target level, links roads to their source and target junctions, and commits. The entire operation happens while AnyLogic is open in design mode with no model run required.
For building walls, adjacent polygons are merged with Shapely's unary_union before being clipped to the bounding box. This avoids creating hundreds of redundant wall segments along shared building edges.
A real example of OpenStreetMap integration
To show what the output of OpenStreetMap data integration looks like in practice, let’s take a real location, a busy intersection near AnyLogic’s Lisbon office:
python .\\generate_markup.py --token YOUR_API_TOKEN --model YourModelName --lat 38.721125137867254 --lon -9.162169799373567 --width 200 --height 200 --roads --walls
The full process of getting this location onto the AnyLogic canvas takes about 4 minutes. Most of that time is needed for drawing the building walls in Lisbon's dense historic urban area, where many small, irregular polygons must be merged, clipped, and converted into wall segments. Check out below what the imported markup looks like in the AnyLogic graphical editor.
The result is already usable. Roads, junctions, and building outlines appear on the canvas automatically. To confirm that it is an actual markup and not a background image, we can add a CarSource block, which sends cars to random streets across the generated network. Let’s run the model to confirm they drive correctly.
We can see that cars accurately move through the generated network. Is this output perfect? No. OSM data has gaps, and AnyLogic's Road Traffic Library has some of its own constraints. For example, motorway link ramps are skipped, very short segments are filtered out, and complex multi-junction areas may need a manual touch. Some roads may have an incorrect lane count, or a junction might need a small positional adjustment. But the important shift is where you spend your time. A city block that once took hours of careful tracing now becomes a short import followed by a few minutes of cleanup. This is a much better starting point than a blank canvas.
Interested in AnyLogic’s real-world usage to optimize complex road systems? Check this case study about Vale optimizing mine traffic management with simulation.
What else can the design-time API do?
The same pattern works for any external spatial format. With an AI agent to help figure out the conversion logic (parsing an unfamiliar file format, mapping its geometry to the right AnyLogic element types), the barrier to automation drops further. Point an agent at the format spec, describe what you need, and iterate:
- OpenDRIVE (.xodr) – the standard road network format from the automotive industry, a natural fit for Road Traffic Library markup.
- LandXML – track alignments and survey geometry that can drive Rail Library markup.
- CAD / BIM exports – floor plans and facility layouts map to both Pedestrian Library walls and zones and Material Handling Library markup like conveyors, paths, and stations.
FAQs
Can you explain the key features of OpenStreetMap?
OpenStreetMap (OSM) is a free, community-maintained geographic database that provides detailed real-world spatial data for roads, buildings, railways, pedestrian areas, and many other map features. Its characteristics make it especially useful for simulation modeling and OpenStreetMap data integration workflows.
What is OpenStreetMap data integration in AnyLogic?
OpenStreetMap data integration in AnyLogic is the process of importing real-world spatial data from OpenStreetMap (OSM) into a simulation model. Using Python libraries like OSMnx together with the design-time API, modelers can automatically generate roads, junctions, and building walls directly on the AnyLogic canvas.
What is the AnyLogic design-time API?
The AnyLogic design-time API is a Python-based interface introduced in AnyLogic 8.9.7 that allows users to create and modify model elements programmatically during model development. Instead of manually drawing elements in the graphical editor, users can connect external Python scripts to a running AnyLogic instance and generate model structure automatically.
Can the design-time API create markup for libraries other than Road Traffic?
Yes. It covers all spatial libraries in AnyLogic. The OSM-to-AnyLogic script in this article uses only a small part of what the API supports.
Where does the markup data have to come from? Does it need to be OSM or a map?
No. The API does not care about the data source. The official AnyLogic example reads conveyor and path layouts from an Excel file. You can use a CAD export, a GeoJSON file, a database query, or even a procedurally generated layout computed in Python. As long as your script produces coordinates and connectivity, the API will draw the result in AnyLogic.
Once the markup is generated, does the model still work like a normal AnyLogic model?
Completely. The design-time API writes directly into the model's graphical editor. It creates the same Road, Conveyor, or Wall elements you would place by hand. After the script finishes, you work with the model as usual. Add process logic blocks, connect them to the markup, run experiments, and publish it to AnyLogic Cloud. The generated markup is indistinguishable from manually drawn markups.
Try OpenStreetMap data integration yourself
This OpenStreetMap integration example is only one possible application of the design-time API. The same approach can be extended to many other spatial data sources and industry formats, enabling faster and more scalable simulation model development workflows.
The script and a ready-to-run AnyLogic model from this blog post example are available on GitHub. Download AnyLogic for free and try this OpenStreetMap data integration workflow today.
