8 June 2018

The public release of BigData Earth’s Location Profile APIs is a milestone in our vision of achieving API-first, cloud-based big data analytics and innovative solutions. [Update 31 August 2018: APIs Version 2.0 out of beta]

The set of APIs released now reflects our substantial R&D in the following major applications over the past two years:

  • Property information and asset management

  • Emergency and insurance

  • Natural hazards and climate change impacts

  • The news media and news reporting

Our application-oriented APIs leverage some of the best publicly available datasets from government agencies, and focus on analytics, insights and reporting. APIs return a set of accessible location metrics in many forms, including PDF report, chart, image and animation. The Location Profile APIs have enabled the development of our two portals to provide property location and hazard risk information:

Details about data models, schemas and code samples of APIs are documented at BigData Earth’s Developer Portal https://Developer.BigDataEarth.com/

Figure 1: BigData Earth’s developer portal for Location Profile APIs

1. Introduction

Application Programming Interfaces (APIs), be they desktop- or web-based, are building blocks in modern programming to make computer programs or web applications much simpler, faster and more powerful. BigData Earth’s Location Profile APIs are a set of RESTful APIs, which use the conventional HTTP protocol for data exchanges. A typical request for our web APIs is in this form:

https://api.bigdataearth.com/au/location-analytics/lat={lat}&lon={lon}&type={type}&uid={uid}

In the query string (in red), four input parameters are required (Figure 2):

  • Geocoded location (with latitude and longitude)

  • Product type

  • Usage id

We link product type (from a product perspective) and usage id (from a usage perspective) to refine the development of each API for certain applications. A single request can return a multi-page PDF report (as many as 40+ pages).

A typical data model, containing properties of parsed input parameters and web links to outputs, is shown in Figure 3. The formats of inputs, outputs and data models are similar for all APIs released.

Figure 2: Typical query parameters in Location Profile APIs

2. Location Profile APIs, more than just location APIs

A number of differentiators:

  • Location Profile APIs return an integrated set of location metrics about a site and its immediate neighbourhood. In this way site-specific location information is enriched with local context.

  • Our APIs not only retrieve location information from multiple spatial databases, but also implement spatial analytics (e.g. terrain analysis) on the fly for contextual insights.

  • The development of our APIs is with a number of potential applications in mind, so some essential domain knowledge can be imbedded.

From a user’s or developer’s perspective, it is very straightforward to use integrated APIs. If location information is too scattered or piecemeal, it would still be a daunting and time-consuming task for developers to interpret and consume numerous APIs from multiple vendors.

Our high-level, application-oriented APIs with location metrics in many forms can be complementary to other mapping APIs widely available today (e.g. Google Maps APIs).

3. Coverage

Current Location Profile APIs cover three regions: Australia, the Contiguous US and the rest of the world, with varying levels of details in underlying data. Related API endpoints are in the forms below:

https://api.bigdataearth.com/au/location-analytics/{query string}  – sample outputs

https://api.bigdataearth.com/us/location-analytics/{query string}  –sample outputs

https://api.bigdataearth.com/ww/location-analytics/{query string}  – sample outputs

Each of the above API endpoints returns an integrated location profile report. We also make theme-based APIs returning more specific results:

https://api.bigdataearth.com/au/bushfire-analytics/{query string}

https://api.bigdataearth.com/au/flood-analytics/{query string}

https://api.bigdataearth.com/au/exposure-analytics/{query string}

https://api.bigdataearth.com/us/vegetation-analytics/{query string}

https://api.bigdataearth.com/us/flood-analytics/{query string}

https://api.bigdataearth.com/ww/elevation-analytics/{query string}

https://api.bigdataearth.com/ww/exposure-analytics/{query string}

Our APIs have access to a number of open authoritative datasets from government agencies, including Geoscience Australia and the USGS. We often add pre-processing and critical evaluation to make sure the dataset is suitable for intended applications. The data sources analysed are acknowledged in the output of each API product.

As our API workflow is generic, it is flexible to rapidly digest other finer-resolution, domain-specific datasets (e.g. LiDAR-based DEM for flood modelling, hazards data for risk analytics, and company exposure data for asset management).

Our backend servers and data analytics engines are resided in and powered by Google Cloud Platform.

4. Examples

The developer portal shows code samples in different languages (e.g. Curl, JavaScript, Python and PHP) for application and system developers. Here we demonstrate an application of drawing elevation profiles at four directions for a location point around the world (Figure 4).

Figure 4: Typical elevation profile chart from a demo elevation analytics API

The use of API usually requires a unique API key (containing both key name and value) for validation and secure data access. The API key name could be varied (e.g. apikey, x-api-key, or cp-Apim-Subscription-Key). API key is often put in HTTP request Headers, but sometimes in the request string up to certain setup.

 

Example 1: without API key (usually for accessing data that does not need any protection or restriction)

– curl (use curl command line)

curl "https://api3.bigdataearth.com/test1/elevation-analytics/lat=-30.123456&lon=150.123456&type=1101&uid=20189000"

– Web browsers (copy the HTTP request below into browser address bar and run, e.g. Chrome, Firefox)

https://api3.bigdataearth.com/test1/elevation-analytics/lat=-30.123456&lon=150.123456&type=1101&uid=20189000

Example 2: with API key

curl "https://api3.bigdataearth.com/test2/elevation-analytics/lat=-30.123456&lon=150.123456&type=1101&uid=20189000" 
-H "x-api-key: ZHxHXvcYAv40DgCxzxbVPaEF404hu7hf1vFIz3Ej"

These are live examples. Interested users can change latitude and longitude values to get corresponding elevation profile charts. Tips: change the file name extension of the output file from PDF to PNG, a chart in PNG format can be downloaded as well.

(The demo API and API key above are temporary, and if the daily quota is reached, they will become inaccessible. Anonymous test results will be removed regularly.)

Example 3: Test the above with GUI-based API development tool, e.g. Postman

We encourage interested users to explore the developer portal and test APIs. Access key is automatically assigned after sign-in and product subscription. For the demo API, approval is not needed.

If not for web applications, the above access methods can also be used to download products for local uses, even with a batch mode. This might be handy for some users. (Mapping-based interfaces have been provided at our PropertyLocation.com.au and PropertyLocation360.com portals.)

5. Applications

APIs, to some degree like software command lines, can be easily deployed and integrated with your system, so you can help present relevant location metrics at your client’s fingertips. Our Location Profile APIs might benefit a number of location-centric applications, including:

  • Real estate and property search portals

  • Property information and valuation systems

  • Emergency response mapping portals

  • Insurance exposure information systems

  • Catastrophe loss modelling platforms

  • GIS and Earth observation image mapping portals

Our APIs can be complementary to the tools and functions your system is already providing. A developer can resort to third-party APIs to automate and deliver certain on-demand tasks to accelerate application development and gain competitive edge.

A common application scenario is that a client provides our APIs with known geocoded location and requests a location profile report, which will be accessible near real time or in seconds. So your client can get even more location intelligence before making informed location decisions. Customisation can be facilitated to create white-label reports for various application needs and scenarios.

The use of APIs is a paradigm shift in application development. It raises a question on whether to build in-house or get access to a particular set of data and functions from a third party via APIs. (Next blog will demonstrate the use of our exposure analytics APIs for exposure estimation worldwide.)

6. Ongoing Work

We plan to share new applications of our Location Profile APIs in future blogs. Meanwhile, we stress the importance of high-quality data and in-depth analytics and modelling, and aim to develop more domain-specific APIs that are easy-to-use, powerful and scalable. APIs enable faster data and information sharing and system integration, and the use of APIs can significantly improve business efficiency, agility and productivity.

The current release of Location Profile API products opens our resources and marks a start for more collaborations and partnerships in our business development at BigData Earth. If you are interested in exploring our unique Location Profile APIs or creating tailored APIs with your own data, please let us know.