Working with the Archilyse API — A Simple Example of DPOI
The Archilyse API provides a powerful tool to easily assess a whole array of architectural features — both inside and outside of a property. The property might be an office, an apartment or a supermarket — it doesn’t matter.
Features such as internal and external three-dimensional isovist, pathways, physical structure and acoustics can be measured.
To get us started with using the API, let’s work through a simple example. Let’s calculate the distance to points-of-interest (DPOI) for an address in Zürich, Switzerland.
About the DPOI
Carrying out a DPOI analysis will provide us with an array of the closest instance of each point-of-interest (POI). There might be two supermarkets nearby but we are only interested in the closest one. It’s important to note here that when we talk about “closest”, we don’t mean in terms of straight-line distance. The DPOI provides the path distance. In other words how far do you have to actually walk through the streets? We provide routes for car, bicycle and walking and as you might expect — these aren’t necessarily always the same route.
Steps
Below are the steps we need to take. But as a quick overview here they are in brief:
- Get an API key
- Submit the DPOI request
- Check on the status until complete
- Fetch the results
- Profit
Step 1: Getting an API key
You can get an API Key from us by registering on our API management console. Once your account has been activated you can generate an API Key on your profile page.
You must authorise every call to our API with your key. Include it in the header of your requests.
Step 2: Submit the DPOI request
I’ll provide all the requests made here as cURL requests. Should you be interested, you can find the full interactive documentation for our API here with examples in multiple languages.
Submitting an address as part of the body in a `POST` request to the `/simulations/dpoi` endpoint we can easily get the data we want.
Request:
Response:
You’ll notice that the DPOI results aren’t returned immediately. But we see that the `status` is currently pending.
The analysis is carried our very quickly — but not instantly. To prevent unforeseen request timeouts, we don’t wait to send you the results. For larger, more intensive simulations you can optionally provide a callback URL to be notified. However, for this example we can simply checkup on the status of the simulation.
Step 3: Check the status
The response provides us with a `building_id`. We created a building for you to store the results of your DPOI analysis against.
To check on the status of the DPOI simulation we can make a call to the `/buildings/{building_id}/simulations/status` end point.
Request:
Response:
In the response above we can see that the DPOI is now complete and from the timestamps you can see that it didn’t take long at all.
Step 4: Get the results
Now that the simulation is complete, we can fetch the results.
Request:
Response:
Step 5: Profit
Before we can make use of our results — let’s try to understand them. Here is section of the results.
It is providing information for the closest cafe. We are given some basic information; its name, latitude and longitude, category and its flight distance (the straight-line distance on a map). Beyond this we have the distance, and travel duration for three modes of transport — bike, foot and car. Each of these has a score. The score describes how well the address performs in relation to other addresses nearby.
A score of 0.40 means that it is better than only 40% of other addresses; i.e., 60% of the other addresses are closer to a cafe. A score of 0.63 means that it’s better that 63% of nearby addresses. So, a score of 0.5 means better than average.
As we can see, this property is in the top 37% for proximity by foot, but in the bottom 42% and 40% for proximity by bike and car, respectively.
How exactly you leverage this information is determined by your own particular use case. Perhaps you want to add additional information to property listings to draw more users. Perhaps you want help determining a valuation. Perhaps your looking to find gaps in a particular market. Whatever your use case — we’re here to give you the information that helps you succeed. Get in touch if you want to ask any questions.
In our upcoming posts we’ll show you how to make your own tools to process and display this data.
- Mapping the locations with MapBox [coming soon]
- Charting the data with D3.js [coming soon]
- Visualising routes with Processing [coming soon]
