Are you going to AU Las Vegas? If so, my class on InfraWorks 360 API - Sharing Model and Proposal Data will be Thursday, Dec 3rd, 3pm. If you cannot attend, here is the handout, enjoy.
1. Start developing apps based on InfraWorks 360 REST API
To start developing with the REST API, first there are some required background topics. This material will not cover them in deep, but there are lots of resources on the web.
Background
The InfraWorks 360 model data available to be accessed via API is seating on the Autodesk Cloud servers and the protocol to talk with that server is REST (Representational State Transfer). In summary it’s quite similar to connect via regular browser, but with parameters (like when we submit a form on a webpage) and a reply format in JSON (JavaScript Object Notation), basically plain text with a standard notation for objects, properties and collections.
Required Software and Libraries
First it’s required to have models on your account, so you should install InfraWorks 360 and create a model that will be accessed via API. If the model is created locally, it must be synched to the Autodesk Cloud, only then it will be accessible via API. As expected, any local change will not be visible via API until the model is synched again.
The communication code can be written in any language that has support for REST protocols. In fact, as REST is language agnostic, any language should work, but not every language have the libraries to do so. Most modern languages are natively compatible or have libraries to do so. For instance, in .NET, the RestSharp (http://restsharp.org) should have all the main features.
The response will come in plain text formatted as JSON. Although we can read it (human-readable), it’s easier to deserialize into objects on your preferred language. From JSON to .NET Objects, for instance, the Newtonsoft.JSON library (https://www.nuget.org/packages/Newtonsoft.Json ) can do the trick. To clarify, deserialize is the process of converting an object stored into an object in memory. For this process, we need the classes representing the JSON structure. We provide that class structure in .NET (we’ll talk about sample later in this material), just like many other libraries for other APIs.
The samples presented here were developed using .NET with Visual Studio, which is the same developing language supported for AutoCAD Civil 3D (and for other Autodesk desktop prodcuts). This language was selected by convenience and any other language with support for REST should work.
2. Discover the data structure of the API
The API structure is basically the same as the product: for each account, there are models that represent a specific area and contains one or more proposals, with different designs for that specific area, then the features, such as road, buildings, trees, etc.
On the API perspective, the first level resides at https://api.infraworks.autodesk.com, but it doesn’t contain relevant model information, just some basic server information.
Models
The first URL level to provide information is https://api.infraworks.autodesk.com/models and contains a list of models for the logged user, as shown on the example below. Note the id and name of each model, and the model id will be used on the next calls.
Using the model id, the response from https://api.infraworks.autodesk.com/models/:model_id will contain the name, boundary, list of proposals, among other properties. Below is a sample reply:
Proposals
To access a specific proposal, we will need the model_id along with the proposal_name, obtained on the model level. The URL is https://api.infraworks.autodesk.com/models/:model_id/propsals/:proposal_name. As we can see, each level uses a URL build on top of the previous level URL.
Below is a sample response for a proposal call (end-point). Note the list of available features at the bottom, the href parameter contains the URL for each feature collection.
Features
At this level we can access the items (features) placed on the model’s proposal. The URL consists in https://api.infraworks.autodesk.com/models/:model_id/proposals/:proposal_name/:feature_type/ and contains the model_id, the proposal_name and, finally, the feature_type, which will return a list of features.
The feature types can be:
• Barrier
• Buildings
• City furniture
• Constraint definition
• Coverages
• Horizontal and Vertical constraint
• Intersection and Intersection region
• Markup
• Pipe connector and Pipeline
• Point clouds
• Points of Interest (POI)
• Railway
• Road
• Terrain surface and texture
• Trees
• Water
Full list here. After the list, next step is read the feature data itself. Each different feature will have different information, but the calling URL should be in the same format, using the model_id, proposal_name, feature_type and the its id: http://api.infraworks.autodesk.com/models/:model_id/proposals/:proposal_name/:feature_type/:id. Here is a sample response for a tree feature type:
Some feature properties are expected for all types of features, such as revision and id.
Learn how to make calls to InfraWorks 360 REST API
InfraWorks 360 REST API uses the OAuth 2.0 authentication, that requires a key & secret on the developer side, plus a user login & password on the user side. The developer authentication is required to increase security and avoid attacks to Autodesk servers. The user authentication certifies confidentially of each user’s information.
The first step is authenticate using the developer key & secret on https://accounts.autodesk.com server, which will return a authorization token, allowing access to the API. With this token, your application can ask the user to login on the same server and, if ok, will return a verifier, that allows access to the user’s data. This process is known as “2 legged authentication” and is required because a developer and the user are different personas, and both need to authorization, to use the API and read the data.
All requests to the InfraWorks 360 REST API must have a header indicating the type of response required. If not, the server will automatically redirect to the documentation (and will not return API data). The header should include (along with the authentication token) the following “Accept” requirement:
application/vnd.autodesk.infraworks-v1+json
With this header, we just need to connect to the server using the URLs described on the previous topic. Each request will require a different URL (end-point). For instance, to get a model with ID 1234, make a request with /models/1234.
In C# .NET, using RestSharp and Newtonsoft.JSON libraries, it would be like:
// Required since relase May/2015 – TLS 1.2
System.Net.ServicePointManager.SecurityProtocol =
System.Net.SecurityProtocolType.Tls12;
// base client URL
RestClient client = new RestClient("https://api.infraworks.autodesk.com");
// consumer key & secret + authorization tokens
OAuth1Authenticator authenticator = OAuth1Authenticator.ForProtectedResource(
consumerKey, consumerSecret, accessToken, accessTokenSecret);
client.Authenticator = authenticator;
// resource we need to access
RestRequest request = new RestRequest("/models/1234", Method.GET);
request.RequestFormat = DataFormat.Json;
request.AddHeader("Accept", "application/vnd.autodesk.infraworks-v1+json");
// make the call
IRestResponse response = client.Execute(request);
// treat the results
if (response.StatusCode == System.Net.HttpStatusCode.OK)
{
string json = response.Content;
// deserialize the JSON return into objects in .NET
return JsonConvert.DeserializeObject(json, typeof(Model));
}
else
{
// many problems can happen...treat error here
return null;
}
Note this is just a schematic, on a real application, this should be optimized (reuse variables) and adjusted according to each scenario. See next section for more sample code.
Discover sample scenarios of integration
There is a huge number of webservices available on the web, providing all types of data. Most likely, your application will collect data from different sources and mashup different providers and create a unique interface.
How we can we mashup webservices?
First we need to find out what makes sense. As InfraWorks 360 store geolocated city design information, it’s make sense to link to other geolocated data. There is an extensive catalog of webservice APIs at the Programmable Web, check the Mapping and Geography categories for interesting providers.
InfraWorks 360 + Four Square + Google Maps
This sample was originally presented at this blog post and now updated. It reads the buildings of the InfraWorks 360 model and, using the location information, asks the Four Square API for nearby venues. The result is shown at a Google Maps with the InfraWorks 360 location of the building and the Four Square location of the venue found and selected.
Just like Autodesk Cloud APIs, to use Four Square API you will need a key & secret. To get more information about their API program, please visit here. Below is a quick print-screen of the sample running. To use it with your personal account, please visit here. and login with your Autodesk Account (the same used on InfraWorks 360). Note that you must have at least 1 model on that account. The source code is available at the sample sample page.
About the technology: the sample was developed with ASP.NET (server side) and uses JavaScript (client side) to automate the interface with the JQuery library
InfraWorks 360 + Google Maps
This sample aims to show 3D buildings from InfraWorks 360 on web map. As you may know and use, there is a 3D version of the Google Maps where we can see the city (mostly buildings) in 3D. It’s a cool interface. Despite there some APIs around the maps, there is no JavaScript API to interact with the 3D version.
After some searching, I found the John Dyer blog with a nice sample: Drawing 3D Objects and Buildings on Google Maps. After reading and understanding the code, you will see that it is actually a 2 + ½ D, not actually a 3D: the buildings are drawn in perspective to look like 3D.
Using InfraWorks 360 building polygon information and John Dyer’s code to draw the buildings, the result will be like shown below:
And you can try with your models (using your Autodesk Account with InfraWorks 360 models) at this link.
InfraWorks 360 + AutoCAD Civil 3D
Sure we can also integrate with AutoCAD Civil 3D. As you may know some integration is already available via Productivity Pack, but this is just to demonstrate the idea.
This sample demonstrating how bring InfraWorks 360 Roads into AutoCAD Civil 3D as Alignments is available at the Importing Alignment from InfraWorks 360 to AutoCAD Civil 3D blog post and was also the sample presented at my Autodesk University 2014 class SD6503.
