Getting started
Account Creation - Pricing
In order to use COALA's features and incorporate it into your project you first need to create a respective project in the COALA Back-end which, in turn, requires a COALA Account. Each project has a unique API Key (Project Key) which you can use to request data from COALA as configured in the back-end.
Creating a COALA account is free of charge but each project you create in your account requires a monthly subscription. By default, each new project start in the Free Tier, which only allows for 1000 requests per month (See Requests section below for more information on what produces COALA requests). You can upgrade you plan at any point in the project's Configuration page. Find our full pricing on our webpage. Your subscription can be cancelled on a monthly basis, which will also deactivate the respective project. While a project is deactivated, you can still work on and modify it but you cannot request any data from it.
Plugins
In case you are planning to use COALA in combination with Unreal Engine or Unity, we highly recommend that you use our plugins for these two engines.
You can learn more about the Plugins in the following pages
Monthly Requests Limit
Please note that each subscription plan in our Pricing includes a set number of COALA requests per month. A project in the Free Plan will not be able to do more than 1000 requests in a month. If your project is in a paid plan and it exceeds the number of included requests in a month, you will be charged a fee per request.
COALA Basics
Areas
The fundamental concept upon which COALA is built is the Areas (also known as chunks or tiles), which are imaginary squares the world can be conceptually split into. These areas are indexable through the Zoom Level (z) shown in the image below:
Increasing the Zoom Level by 1 effectively halves the length of an Area's side and quadruples the number of Areas the world is split into, essentially providing a more zoomed-in representation of the real world in each Area.
A specific Area can subsequently be indexed
It's important to note that COALA only functions at Zoom Level values 14, 15, and 16. The default Zoom Level for COALA is z = 14.
Cells
Each of the Areas in any of these Zoom Levels is then divided in 2025 (45 x 45) Cells. That means that for the default Zoom Level of 14, each Cell represents an area of approximately 33 x 33 meters on Earth's surface.
Through COALA you can fill each of these Cells with context information of your choice (See also Contexts).
Requests
A request is practically an API request made to COALA in order to
receive data according to your configurations configured
send data to COALA for further usage
COALA Requests
COALA makes a COALA request for each Area it needs to load, which means that when a user starts the app or moves to a new Area, new Areas need to be loaded and, therefore, new data also need to be requested.
You can take a look into the world and observe how new COALA Area objects are created and deleted.
In addition, there is an update system running in the background (or you can create one) which generates additional requests depending on your configurations. For example every X seconds make Y new requests, where X is an interval set by you and Y is the number of Areas that need to be loaded/updated. This can be configured in Unity through the Update config.
Geofencing
Setting up a Geofencing area generates requests on a set interval, regardless of whether a user is within this area or not. You can modify this interval through the Geofencing Native Plugin (it's set to 3 seconds by default).
Other User Visibility
Enabling the Other User Visibility feature will generate requests on set intervals, which you can modify through the Unreal and Unity configs.
Custom POI Name Suggestion
A request is made whenever a name/tag suggestion for a custom POI is requested through Unity or Unreal, regardless whether it was done by a developer or a user.
Custom POI Creation
A request is made whenever a custom POI is created through Unity or Unreal, regardless whether it was done by a developer or a user.
Movement Speed (feature not yet live)
A request is generated on a set interval, which can be modified through the Movement Speed config in Unity. The feature is not available for UE yet.
Data Providers and Data Layers
COALA draws most of the data it provides through public sources or Open Source projects and other data sources. You can find further information here.
Through hard work and innovation, the COALA Team designed a layering system to use data from these sources and make them much more readily available and easy for users to work with. All the different types of data that you can use through COALA, such as time, altitude, weather, etc., form the so called Data Layers. By combining these layers in unique ways you can create your own customized ProjectTags and POITags and fully control the data COALA sends to your users with each API response.
COALA Tags
One of the main features that make COALA so effective and efficient is the COALA Tags. The COALA Team has combined and processed the data from our data sources to create Tags which accurately represent most real world contexts, the COALA Tags. Some common examples of COALA Tags are Parks, Water Bodies, or Buildings and even various Moon Phases or Weather Conditions.
You can use these tags to create custom contexts. Basically, you can create your own ProjectTags using COALA Tags, which will then appear in your world's Cells. For example, creating a ProjectTag named "Forest" and setting it to appear in Cells that are part of a forest in the real world will "tag" these Cells with the "Forest" ProjectTag, which you can then use to decorate your map or trigger certain in-app events when a user physically enters a forest.
A list of the most common COALA Tags can be found here.
COALA POI
Similar to COALA Tags, we have also created the COALA POIs which accurately represent the most common Points of Interest found in the real world, such as Restaurants, Churches, or Museums. Unlike COALA Tags which are applied on Cells and thus represent an area, COALA POIs represent an exact point in the real world.
You can use a combination of COALA POI and COALA Tags to create you own custom POITags. For example, you can create a POITag named "Bars" and set it to spawn "Bar POIs" on your map at any location where there is a bar in the real world or trigger certain events when near a real-world Bar.
Creating Custom Data
The possibilities when using COALA are only limited by your imagination. If you find that the existing COALA Tags and COALA POIs do not cover your project's needs, you can also import your own data directly into your project or contact us at support@thoughtfish.de to further discuss the creation of the layering option you wish to incorporate.