Building a API for Geodesign


In this article, I will describe a API for the geodesign workflow, the goals and the recent progresses we have made at Geodesign Hub to achieve this.

If all you have is a hammer, everything looks like a nail.

In most creative and professional fields, this quote is relevent. I have come across many professionals whose thinking is shaped by the tools being used. In some cases, the tool and its capabilities guides the solution. But how would design and planning look like if it were agnostic to the tools being used? What sort of level of abstractions would such a design process require?


Geodesign is a process of design. I have written earlier about the differences between geodesign and “traditional” design. I built Geodesign Hub and it represents this new class of software that works quite differently from existing planning support tools. Prof. Uri Avin of the National Center for Smarth Growth describes this quite nicely in the following diagram, the right most diagram is how Geodesign Hub works.

Geodesign Hub compared with other tools (source: Prof. Uri Avin)

Therefore, Geodesign Hub is essentially a workflow that enables interoperability between different models and tools seamlessly while enabling the core task of collaborative design.


This software model assumes different systems working independently of each other without a requirement or necessity to have a particular specialized software installed. Given the interdisciplinary nature of geodesign, this inclusive structure works better and enables tools and people from industries and domains that you would not traditionally associate with design and planning to participate as a equal citizen in the process of design. It works well with free or paid, old or new, simple or complex, properitary or open source software.

The Goal of Geodesign API

I have had a number of discussions with Dr. Stephen Ervin about the goal of a geodesign API. Dr. Ervin is one of pioneers in the field of geodesign and has been actively involved in the development of theoritical foundations of the discipline. The outcome of our discussions can be summarized by the following:

“The goal of a Geodesign API is to develop a extensible specification and format for describing GEODESIGN MODEL(s) – algorithmic processes that take one or maps as input and produce output in some specified format (one or map(s), number(s), data structure(s), etc.), to be incorporated within geodesign processes.

This is quite amibitious but it also encapsulates the challenge in planning and design: the ability to describe the world from vastly different lenses in a way that other people can understand and make decisions. By using the lanugage of datastructures, maps and numbers we are ensuring broad inclusivity and agnostic to the tools where this data is created. When I set about building Geodesign Hub API, this was the goal.

Geodesign API

The API documentation can be accessed at:

The API fairly simple and straightforward structure and it enables you to take out all data and also submit data in the form of maps and numbers. They There are four main APIs:

  • Projects API: Geodesign Hub works of geodesign projects, all aspects of projects can be queried using this API.
  • Systems API: A project has a number of systems, these can be simple things like, hydrology, transport, housing etc. but also can be compound such has green infrastructure
  • Diagrams API: Diagrams are ideas for improving the systems, this API enables you to query and add diagrams.
  • Change Teams API: Once diagrams are created, they are then synthesized to create designs by teams of people. All aspects of the designs, and negotiations can be queried through this API.

And thats it!

Geodesign Hub API Documentation


What can be built using this API?

There are many things that can be built using a API like this:

A full list of growing plugins is here:

All of existing models and tools should have no problems in interacting with the design process. All are welcome as equals to the design process.

In addition, in the next few months, I am focusing on building a new Financial Analysis plugin for geodesign and also pushing the envelope to link deep learning and other modern Artificial Intelligence technologies to the problem of design.

Want to learn more?

We host regular webinars and tutorials about this API, please feel free to drop me a email to pre-book a place in the next one in the next month.

Decoding (Geo)design DNA

In this article, I will describe a new tool I created that helps you look deeper into a geodesign process. It enables you to gain an understanding of the design method and also opens up large number of possibles for fundamental research on collaborative (geo)design methods for different scales, geographies and designers.

Design is both a verb and a noun. Geodesign is a collaborative activity, a process for creation of a design or many designs. Geodesign Hub enables a collaborative workflow where people from different professions and backgrounds get together and go through a process to create many designs and iterate on them negotiating with each other to come to a (set of) consensus designs.


In the context of geodesign, I take a contrarian stance. As a culture, we are accustomed to hearing about the “genius” in design professions. Beyond a certain scale, however, I believe that the best designs are not ones that come out of creativity of a single person but through a collaboration. The output is more than the sum of the parts. That is for any design larger than a certain scale “emergent creativity” of a team is more important than individual brilliance. Therefore, if this process of collaboration can be deconstructed then we can understand how designs are produced and move forward on identifying appropriate methods for a given scale.

Design Methods

There are two important considerations with respect to designing in general:

  • Size and scale matter when it comes designing: strategies used to design a house are not the same as ones used to design a city.
  • Design strategy or “ways of designing” differ for every group or individual based on their experience, collaboration effectiveness, type of problem etc.

As I describe above, the design method plays a crucial part for effective design interventions. In a collaborative fast paced design setting that produces a number of designs and negotiations, how can a design method be decoded? This is a hard question and needs further research. But when I started to think about this, I realized that there are no tools available to conduct this type of study.

DNA of a Design

To understand the design method, the first thing to do is to deconstruct the process of making the design: break down the components and have a way to “walk through” or navigate the design process. It is akin to someone recording the process of assembly and playing back over to see how it is made. This technique is commonly used in Chess (although usually for a single player). This kind of analysis can also be done with modern software development with version control systems like Git or Mercurial. Using these tools, changes made to a software can be tracked quite effectively to deconstruct or jump to individual states in the history. Can these techniques be applied to architecture, landscape architecture and geodesign?

Geodesign DNA

The geodesign workflow as implemented in Geodesign Hub lends very nicely to this kind of analysis. Using the API, I built a open source plugin: Geodesign DNA. It reads the designs built on Geodesign Hub and then produces a detailed history for a design. In realtime as it progresses and the designer iterates on it. In addition, it produces visualization that help understand how diagrams are used by the designers as they iterate on a design and negotiate to make changes. You will need to have done a geodesign project using the workflow to get the credentials but some features.

  • Visually see history of a design as it is being made (like most modern source control tools).
Visual and Text history of all designs
  • Quickly see how designs change as designers add / remove new diagrams to their design.


This slideshow requires JavaScript.

  • Visually see these changes on a grid
Move slider to see design changes.


  • Finally, see how the diagrams were added or removed as the design process progresses. The y-axis in the chart below are the diagrams and in the x-axis is chronologically ordered designs with the one on left produced first and the right most being the last. The connected lines mean that the diagram was used in consecutive designs. The longer the line, the more robust the diagram idea is for the designer and their team and they kept on picking it as they iterated on their design.
Diagrams and Design Evolution

DNA Library

Every design project is different but the chart above is a unique finger print of the design process and the diagrams and their movement over time (shown above) as genes. Together they from the DNA of the design. Across different design exercises, A library of these can produced as shown below with each design having a different fingerprint.

The images above are like a recorded video of the design process that can be played, rewinded, skipped etc. and it opens up many possibilities for fundamental research on design methods in geodesign.

Why is this important?

By understanding the way to design in a purely digital form would mean that the most effective design method for a particular scale can be taught and analyzed with empirical data. Secondly, these methods being purely digital can be fed to machine learning / AI / Big data algorithms to construct a way to design. Imagine this: we are teaching a machine the actions a group of designers take to solve a problem.

Lessons Learned

The more I work in the field of geodesign the more I realize that tools that are available in other professions are simply unavailable for design. The DNA tool described here uses techniques very prevalent in the software world. Most engineers working in a modern software development environment are very skilled in source control management to track and manage their work. Even more broadly, Dropbox for example enables you to monitor changes to a file and revert back to a old version or un-delete a file if you delete it by mistake. So while these technologies are available broadly, they do not exist natively for people in the design fields. I wanted to see how a version control system built for the process of designing a master plan for e.g. look. Can it be done? This is my version of creating a design version analysis tool that enables you to revert, edit, merge and visualize changes to your design as it builds over time.

Next Steps

This is just the beginning of a large amount of work that can be done in the field. The first one that comes to mind is to take this analysis forward and instead of listing the changes to the design, it would be interesting to see what these changes mean to the design. Does the change area increase or decrease? Does it make the design “better”? etc.

In addition, I aim to build a library of these design fingerprints at different scales and projects (which we have on Geodesign hub) to explore and test the “Ways of designing” methods as described in a Framework for Geodesign, the seminal book from Prof. Carl Steinitz.


Currently, we use this tool to understand a project deeply. We use it to identify key diagrams, key steps in the negotiation process and also build experience in running these studies. This tool is available for all projects done on Geodesign Hub and is open source. It uses the Geodesign Hub API and is written in Node and JavaScript. You are very welcome to take a look at the code and submit pull requests to improve it.



A text based geodesign dashboard

In this article, I will describe a text based dashboard for geodesign projects that I set about building. I like to work on side projects and this is one.


I too have been guilty of building crappy dashboards. It has been some what of a hobby for me to rectify this and over the past few years I read a lot of material on this. At this time, all I can do is recommend some amazing books:

Of course there are others and I intend to write more about books that I have researched at a later time.


With that out of the way, I wanted to share a side project that uses the Geodeisgn Hub API. Meet Geodesign Hub Dashboard, a text based status dashboard for projects created on Geodesign Hub. Essentially, once you enter your API token and the project ID (Geodesign Hub works on projects) you can see a text based “dashboard” of all the project data.

Dashboard main
Dashboard main screen


I have been thinking about dashboards for some time now. During my time at UCL CASA, there were a number of researchers building city dashboards. Most notably the London dashboard. It tells you at a glance what is going on in London in near real time. This idea has been replicated in many cities e.g. Dublin, Edmonton etc. This kind of a real time feed is quite useful in administration and getting information quickly. One thing that I do not like however, is that in these dashboards is the overuse of charts and text. So I went back to the basics and decided to make a text only dashboard in the spirit of old fashioned stock tickers as shown below. Using only text and colors is very challenging and fun at the same time. Geodesign is a emerging field and by avoiding the use of charts etc. I am hoping to establish key data that are required to be monitored in a study.

The original text based dashboard (source)

What it does

Once you enter your API Token and Project ID, it queries the  Geodesign Hub API to show you the project name and description, the systems, the diagrams added under each system in a grid, the change teams and the participants in the project with a link to their profile. This is shown below:

Project details and diagram information
Screen Shot 2016-06-01 at 10.18.46
Change teams and project users


I thought this was good enough for a start. With this information, you can see at a glance most of the data in the project: the systems and the improvement ideas and also the change teams who will build a design based on these diagrams. In addition, the IDs of diagrams are displayed so it is easy to download the geometries via the API. I found this to be quite useful while developing plugins.

How I built it

This plugin utilizes the Geodesign Hub API more specifically the GET methods to get all data from the project. I then created a Node app using  Express, Request and Async node modules. On the front end, I use the DataTables to build the grid, Humane JS for notifications and of course JQuery. There is one call that posts the credentials to the server that then asynchronously makes call to the API and returns once the calls have been resolved. I then packaged it up and deployed it on Heroku and to the Github repository. It is open sourced and MIT Licensed.


I have limited experience with node.js. I have been using Javascript and I consider myself to be a bit beyond beginner at this point. Node seems to have almost infinite libraries to do do this kind of stuff, I had to familiarize my self with some of the ecosystem. Using JavaScript on node is a learning experience. I extensively use Promises on the browser and even with that it was challenging to figure out how Promises can be implemented on a node server. Git and Heroku deployment was relatively straightforward.


Technology: I learned quite a bit building this in Node. My original idea was to build a desktop app, I looked up some libraries in Python e.g Kivy, using Electron etc. however I thought a small node app might be handier. I think I can always package it as a cross platform desktop app anyway. I also found out that there were no major changes required to the API to make a app like this and it worked quite nicely.

Geodesign: I wanted to start with a very basic text based dashboard for a geodesign project administrator. One that gives a overview of the design project as it progresses. I have been able to identify key pieces of information that are necessary for this: diagrams, systems, change teams and members. I intended to add information about the generated design as well but decided to hold off since it was too much for the moment.

Whats next?

This type of dashboard should help in administering a project. We do a number of workshops every month and I plan to use this dashboard to the next time and also ask other administrators for their opinion and feedback. It is faster than loading all diagram data and geometries.

Technically, I intend to add more information (text only) to this. I have decided to not use maps etc. at the moment. There are a number of technical improvements that can be made: better async handling, building a Geodesign Hub node API module etc. but that is for later.

Get involved

If you are interested in getting involved, contributing or providing feedback or just have more questions, please feel free to reach out. My email address is on the contact page and also am on Twitter.


The differences between geodesign and traditional design.


  • In this article, I argue that geodesign should be thought of as a process not a tool or a branded exercise.
  • We are at a point where advances in tools and technology can be leveraged to have a collaborative, integrated a design and impacts analysis.

What is Geodesign?

Geodesign has been used (or misused) as a buzzword lately in social media, conferences and other forums. In recent years, there are has been a proliferation of academic courses and conferences organized around the topic. Critics argue that geodesign is not new or that it is an invented term used mostly for marketing. They argue that designing has been a activity that is carried on for thousands of years and essentially the movement of geodesign is just a continuation of that.

Geodesign is a workflow

While the critics are partially correct, there are some aspects of geodesign that make it fundamentally different from what we have experienced before. To understand this, we need to think about the following: Is Designing an art or science? Obviously, there is no absolutely correct answer to this in the context of geodesign, it is a mixture of both. A more nuanced question is the following: Is the process of designing art or science? When an architect designs a building or a home there is an inherent internal creativity that results in the form. In the same way when a climate scientist studies sea level rise, it is underpinned by solid scientific and technical theories and models. However, one cannot design a home using climate change models nor can a single person guided by their experience and creativity design a solution for sea level rise. The methods of designing a house do not work to design a plan for climate change (and vice versa). One of the reasons  why these methods are not interchangeable is that as the scale gets larger collaboration between different disciplines of design and science plays a increasingly crucial role.

The process of geodesign is most useful and effective when it is used collaboratively not to design a single house or to design a climate mitigation system but in the scales that are in the middle: collection of buildings, neighborhoods, wards, cities, city regions, multiple counties. There are three different trends with collaboration technologies that converge to make geodesign relevant and powerful.

Firstly, there has been maturing of enabling technologies. The smartphone revolution, the relative ease at which broadband is available means that there are more people connected and engaged. This also has meant that the underlying infrastructure and technologies that power all the Apps and data the internet has finally matured and is capable enough to serve billions of users. The design community has become much more amenable to integrating technology into the design process over the past number of years. And that the increasing horsepower of technology allows for much more rapid and fluid design prototyping and analysis leading to better communication and iteration of ideas. As scientific progress is made, we have developed a deeper understanding of the delicate interconnections between nature and the built environment. The design professions are tasked with a leadership role to orchestrate the complex interconnected systems that are at play in a study area.

Secondly, there is a general understanding that the major problems facing our planet necessitate a collaborative approach to problem solving. Thus people from different disciplines and domains including people of the place need to bring in their expertise and knowledge to design solutions. This is sometimes enforced and mandated by legal frameworks such as the European Landscape Convention and others.

Thirdly, we are in the midst of a geospatial computing revolution with broad availability of open data and mapping technologies. And there is a small ecosystem of startups focused on mapping technologies that have attracted venture capital and are well on their way to success.  (Startups like Azavea, Mapbox and CartoDB etc.). These trends open up an opportunity to build the next generation of design tools that enable collaboration, leverage open data and standards. Fundamental advances in general purpose software: such as version control, data analysis and processing, cloud computing also accelerate this trend.

Design Methods

In the case of design however methods play an critical role. The technological and societal changes also mean that design methods and experience that has worked for many years can be updated and modernized using software. What does this mean? It means that designs can be produced faster, they can be compared more efficiently (and rejected quicker), they also mean all analysis and feedback is done in near real time collaboratively. This is the essence of the geodesign process.

This makes geodesign fundamentally different: the process of design is different. There is no distinction between design and analysis it combined into one seamless operation that can be understood by people of different professions, experts and non-experts alike. All of this is powered by collaborative software that accommodates different design methods and scales.

What do you think makes geodesign different?

In the coming weeks, I plan to write a series of blog posts on the fundamentals of the geodesign workflow.


I would like to thank Matthew Baker of and Critter Thompson of PlaceMatters for their comments, feedback and reviewing this post.

Geodesign Hub

Geodesign Hub is a modern planning and analysis tool to collaboratively design better urban plans with the power of data. Creating and running geodesign projects is free for individuals and there is a comprehensive support portal to help you get started. For companies, we offer paid professional support and training.

Generating Buildings and Roads from GeoJSON

Recently, I have been working quite a bit with OSMBuildings, the awesome library that lets you visualize OpenStreetMap buildings in 3D in a browser. My interest is in planning and design and it got me thinking as to how OSMB can be used to visualize planning and design ideas.


I built Geodesign Hub to enable rapid early stage planning and design. Most design problems are “wicked” in that there is no obvious answer and the tradeoffs are not apparent. In essence, given that design is a creative activity, one could have almost infinite design solutions to a problem. One of the characteristics of a “wicked” problem is that they are rarely solved by a individual, they are best addressed when solved collaboratively in a  multi-discipline team. A interesting Quora answer about this here.

Geodesign Hub helps team of people to build plans and designs, rapidly iterate on them and in the process eliminate design ideas that don’t work and focus on the ones that do. What this does is it enables teams to go from a solution space that has literally trillions of designs to one that has about six or seven. Then they negotiate over these six or seven designs to come to one or two final ones that have broad consensus and acceptability. All of this is done very rapidly using technology we have built.


Since we deal with early stage designing, visualization is not that important, what is more important is that different ideas are tested in isolation and also how they work together. However, as the teams get closer and closer to a negotiated design visualizing a design in 3D becomes important. Geodesign Hub is a open system where all data is entered from outside and can be taken out of the system for further work using the API. I have been fascinated with the progress Jan has made with the OSMB library and decided to hack on a link.


Geodesign Hub enables you to take out as GeoJSON (and Shapefiles) all data into the system including the designs. So I took out a design from our sample project as GeoJSON, essentially it is a FeatureCollection with some polygons and linestrings that depict a plan for a place. On a side note, there is a Python client for the API. So I went about writing code that downloads GeoJSON that then can be pasted on the tool to generate streets and buildings. And the output looks like the following:


Geodesign Hub 3d Viewer


Admitted this is a very basic scene but here is what is going on, the script takes a GeoJSON polygon, checks if it should be extruded by checking the “height” property. It can be either ‘ag’, ‘ug’ or 0, where ag means above ground (therefore needs to be extruded), ug means underground and 0 means on ground.

Once the script encounters a ‘ag’ property in the JSON, it extensively uses turf.js library to create a point grid for the extent of the polygon, then get the points within the polygon, then create buildings of random height, clustered together. The ‘reqtag’ property has the building type information from Geodesign Hub, where ‘SMB’ means small and medium buildings, ‘LAB’ means large buildings etc.

Once these buildings are created, if the user checks the road generation property, we create orthogonal streets so that every second building has access to a road. Admittedly, this is primitive but it works for small urban scale. I was talking to Filip Biljecki and he pointed me to two terrific papers for road generation here and here and for larger regional polygons these methods are more relevant. I have the basic code in place for this building heatmaps and clustering buildings on the heatmap. My plan is to test this a bit more.

Once the streets are generated, I remove the buildings on the streets and create send the GeoJSON back to the browser to be rendered in OSM Buildings.


The colors are specified by Geodesign Hub and they represent a system, in this case the red may be a commercial / industrial area, the orange housing and green agriculture. These color codes are inherited from Geodesign Hub.

Next Steps

Obviously, this is a very basic scene but it can be useful to show early stage design ideas in planning. I am going to add more buildings types, make it more realistic in sync with capabilities of OSMB in addition to making it faster.


All of this is open source on GitHub (GDH3DViewer) and the buildings and street generation code in JavaScript is at: 3dlib.js.

I would love any feedback, or thoughts or opportunity to collaborate on this.

Completed my PhD in Geodesign

I recently completed my oral exam for my PhD and passed with minor corrections. I am in the process of getting the corrections reviewed and then submit. I am just getting started in this journey with Geodesign and Geodesign Hub. A lot of things to say but my sincerest thanks to all my advisors and staff at CASA.

A image and blog post at the CASA website below.


Left to right: Prof. Carl Steinitz (mentor), Prof. Henk Scholten (external examiner), Hrishi Ballal (the successful graduate), Prof. Brian Orland (external examiner via Skype), Prof. Mike Batty (supervisor). Dr. James Cheshire was also supervisor but not available for the photo.