GeoSimulator Documentation

Start testing your awesome iOS & Android apps with GeoSimulator.

GeoSimulator is a geolocation testing application, which helps developers and testers test the geolocation aspect of their applications right from their desktop. Our platform allows you to create a new breed of applications that will require globally simulated locations. Imagine a tour app where your users can virtually tour the streets of Paris while sitting in Idaho. Imagine creating educational content that are tied to specific global locations and being able to deliver the same right from your desktops. Your imagination is the limit.

With our easy to use APIs or SDKs, you can simulate user motion in your location aware application without roaming the streets or wasting gas money. This way you know exactly how your users will experience your app in various locations all over the world – right from your desktop!

With the GeoSimulator platform, you can create Geo-fences anyway you want – create arbitrary zones using polygons, polylines, circles or even create arbitrary paths! Building a more complex GIS or LBS application? Need to simulate locations? Just call our APIs or use our SDK!

In this article, you'll learn some basics about how to use GeoSimulator and find resources that can help you as you work.

Create New Account Login

About GeoSimulator

GeoSimulator was built by Nisos Technologies, an independent bootstrapped software company and makers of fine products such as Karma, Sandcrate and AeroD. GeoSimulator was built to take geo-testing process into the future. We wanted an application that not only looked and worked great, but was also powerful enough to help developers create amazing apps.

GeoSimulator is a powerful platform to build, simulate and monetize location based solutions. It enables mobile developers, OEMs and enterprise partners to quickly test rich geolocation functionality to applications and devices. It includes a complete, real-time toolkit for geolocation, geotargeting and location analytics services with language agnostic SDKs. GeoSimulator is based in New York City.

How GeoSimulator can help you

  • Real-Time Location Services: Developers can implement full-featured, real-time location services, with minimal time and effort. GeoSimulator offers SDKs for iOS, Android now and will be adding more in the future.
  • Real-Time Geotargeting /Geo-triggers /alerts: Developers can test alerts/triggers based on proximity to or presence in arbitrary paths/neighborhoods/geo-zones.

Technical Support

API Reference Docs
Our API Documentation contains in-depth information on each of our APIs, including details on making requests, rate limits, OAuth, reading responses, testing queries, and common error messages.

Language Specific SDKs
If you are developing an app that requires access to the Geosimulator API, we have a number of code examples and programming language-specific libraries (Android, iOS & Titanium) to help you get off the ground quickly.

Browser Support
GeoSimulator is a web-based application that works in most web browsers, which means you don't need to download or install any software on your computer. To make sure GeoSimulator works properly in your browser, you should enable cookies, popups, and JavaScript.

Before You Start

Before you start we highly recommend you to read Getting Started guide about how to use GeoSimulator. GeoSimulator's learning curve is pretty easy. If you know how to work with REST APIs - you almost know how to test apps with GeoSimulator. If you don’t, no need to fret - our web portal is so easy and intuitive, it will be a breeze.

For better understanding we recommend you to read documentation articles in direct order like you see them in left navigation.

Getting Started With GeoSimulator

It is really easy to test your app with GeoSimulator. There are two ways to start.
You can either immediately start testing simulations using one of our demo simulations or integrate one of your applications into GeoSimulator.

Let's create our first app from scratch. To do that, you'll need to sign up first

Note:

  1. You'll need to pass these URL parameters in every API: (case-sensitive):
    • "outputType" as "JSON" or "XML"
    • apiKey
  2. If outputType is not specified, by default response will be sent as JSON.
  3. All APIs (except for Login, Signup) require apiKey.

Sign Up

Via web application:

Create your profile by filling in the details. An API key will be generated once you confirm your email address.

Alternatively you can sign up via API:

In the Signup API, enter the email, name, phone (with countrycode), password, confirm password, username and company. Then post the data. After successful registration, you will receive an email confirming the registration process.

User Signup REST API:

https://apps.geolocationtech.com/api/v1/user

Pass the "Content-Type" as "application/json".

And finally, post the following data with appropriate values to the Sign Up API.

Note : The password must be at least 8 characters and must be a mix of atleast 1 uppercase, 1 lowercase letter, 1 number and 1 special charater.

{
"username": "yourUserName",
"password": "yourPassword",
"password_confirmation": "comfirmPassword",
"name": "yourFullName",
"email": "yourEmail",
"company_name": "yourCompanyName",
"number": "yourPhoneNumber"
}

To login to the geosimulator platform, enter the username and password in Login API. Make sure you activate your account first.

Login REST API:

https://apps.geolocationtech.com/api/v1/login

Again pass "Content-Type" as "application/json" in header.

And finally, post the following data to the Login API

{
"username":"yourUserName",
"password":"yourPassword"
}

Add Application

Via web application:

Simply click on 'Create new application' button and follow the steps to create your application via Web Portal.

In these basic steps, you will need to add your application name, details, OS, OS version and an app icon. Once that is done, an appKey will be generated. You can then proceed to add one or more simulations to your application.


Via APIs:

First you'll' need to upload an icon for your application and get it's URL.

Upload icon REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/application/icon

Pass the apiKey in the header of the request.

Browse the image to upload and you will get a imageurl in response. Copy-paste this url somewhere safe, you'll need it while creating the application


And then, simply post the following data in the Create application API and send it. The data to be added are application name, OS, OS version, application description, icon url etc. You will get a response that the application has been created.

Create Application REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/application

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Pass the following data to the Create Application API
os : Android or iOS or Windows or Other.
os_version : AND5, AND4.4, AND4.1, AND4, iOS9, iOS8, iOS7, iOS6, iOS5, iOS4, WIN8, WIN7, OTH

{
"name":"yourApplicationName",
"description":"yourAppDescription"
"os":"osName",
"os_version":"osVersion(s)",
"iconUrl":"link to your icon"
}

Add Simulations

To test your application, you need to add simulations based on your requirement. This is basically just a map where you want to simulate your user’s motion. There are five types of simulations you can test using GeoSimulator. For each simulation, you need to enter a unique simulation name and add an application. You can also add a group name. Group names are nothing but tags, read more about them here.

Following are the different simulation types. Click on "Simulation Types" on the left panel to know more about how to create a particular type of simulation.

  1. By Address
  2. By Random Polyline
  3. By Sequential Polyline
  4. By Polygon
  5. By Circle
  6. By Layer

By Address

Via web application:

If you want to test simulation between point A and B, simply enter “From address” and “To address” and choose between driving/walking.


Via APIs:

Add Simulation By Address REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/address

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Then, post the following data in the body.

{
"testCaseName":"simulation name of your choice",
"fromAddress":"fromAddress location",
"toAddress":"toAddress location",
"application": ["applicationID-1","applicationID-2"],
"dirType":"Walking" or "Driving",
}

The simulation between two location points is created now. Note down the simulation id for reference.


Update Simulation By Address REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/address/simulationID

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Then, update the data in the body of the API as you'd like.

{
"testCaseName":"simulation name of your choice",
"fromAddress":"fromAddress location",
"toAddress":"toAddress location",
"application": ["applicationID-1","applicationID-2"],
"dirType":"Walking" or "Driving",
}

Test Simulation By Address REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/address/test

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Then, post the following data in the body of the API to test the simulation.

{
"testcase_id":"simulationID",
"step":"1",
"speed":"50",
"unit":"kmph" or "mph",
"application": "your-applicationID"
}

Random Polyline

Via web application:

Use your pointer to add points on the map to create a polyline. The simulation will trigger points randomly on the path you have defined.


Via APIs:

Add Simulation by Random Polyline REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/randompolyline

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Then, post the following data in the body of the API.

{
"testCaseName":"simulation name of your choice",
"application":["applicationID-1", "applicationID-2"]
"polyLine":"LINESTRING (42.69858589169842 -90.50537109375,43.07691312608711 -89.637451171875,42.407234661551875 -88.758544921875,41.95949009892465 -89.49462890625,42.1389684045809 -90.406494140625)",
"testGroup":["groupname-1","groupname-2"]
}

After entering all the above, send it. You will get a response message that the simulation has been created. Note down the simulation id for reference.


Update Simulation By Random Polyline REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/randompolyline/simulationID

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Enter any changes you want in the body of the API

{
"testCaseName":"",
"application":"",
"polyLine":"LINESTRING (each latitude longitude pair separate by a ',')",
"testGroup":[""]
}

Test Simulation By Random Polyline

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/randompolyline/test

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Then, post the following data in the body of the API to test the simulation.

{
"testcase_id":"simulationID",
"step":"1",
"application": ["applicationID"]
}

Sequential Polyline

Via web applcation:

Use your pointer to add points on the map to create a polyline. Also add a distance after which you'd like the simulation to trigger points on the path sequentially. For example you create a path from Central Park, NY to the Empire State Building, NY and you add sequential distance of 0.5 mile, the simulation will trigger after every 0.5 mile.


Via APIs:

Add Simulation By Sequential Polyline REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/sequentialpolyline

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Then, pass the following data in the body of the API:

{
"testCaseName":"simulation name of your choice",
"application":["applicationID-1", "applicationID-2"],
"polyLine":"LINESTRING (42.69858589169842 -90.50537109375,43.07691312608711 -89.637451171875,42.407234661551875 -88.758544921875,41.95949009892465 -89.49462890625,42.1389684045809 -90.406494140625)",
"polyLineDistance":"distance",
"polyLineDistUnit":"distance unit km or miles",
"testGroup":["groupname-1","groupname-2"]
}

After entering the above, send it. You will get a response message that the simulation has been created. Note down the simulation id for reference.


Update Simulation By Sequential Polyline REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/sequentialpolyline/simulationID

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Enter any changes you want in the API

{
"testCaseName":"",
"application":[""],
"polyLine":"LINESTRING (each latitude longitude pair separate by a ',')",
"polyLineDistance":"",
"polyLineDistUnit":"",
"testGroup":[""]
}

Test Simulation By Sequential Polyline REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/sequentialpolyline/test

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Then, post the following data in the body of the API to test the simulation.

{
"testcase_id":"simulationID",
"step":"0",
"application": ["applicationID"]
}

Polygon

Via web application:

Use your pointer to add points on the map to create a polygon. The first point and the last point must be the same to create a polygon. The simulation will trigger at random locations inside the polygon you have defined.


Via APIs:

Add Simulation By Polygon REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/polygon

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Pass the following data in “Create simulation by polygon” API:

{
"testCaseName":"simulation name of your choice",
"application":["applicationID-1", "applicationID-2"],
"polygon":"POLYGON ((41.236511201246216 -90.3515625,42.39912215986001 -89.945068359375,42.342305278572816 -88.736572265625,41.48389104267176 -88.681640625))",
"testGroup":["groupname-1","groupname-2"]
}

After adding all these values, send it and you will get a response message that the simulation has been created. Note down the simulation id for reference.


Update Simulation By Polygon REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/polygon/simulationID

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Enter any changes you want in the API

{
"testCaseName":"",
"application":"",
"polygon":"POLYGON ((42.671236074397775 -91.46230815937497,41.246521741991214 -91.68203472137497,41.546521741991214 -91.68203472187497,42.671236074397775 -91.46230815937497))",
"testGroup":[""]
}

Send it. You will get a response message that the simulation has been updated.


Test Simulation By Polygon REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/polygon/test

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Enter any changes you want in the API

{
"testcase_id":"simulationID",
"step":"0",
"application": ["applicationID"]
}

Circle

Via web application:

To test your simulation in a circle, simply add a center point coordinates ( for example 40.782881, -73.965409 for Central Park, NY). Also enter the circle radius with proper units (km or miles). The simulation will trigger at random locations inside the circle you have defined.


Via APIs:

Add Simulation By Circle REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/circle

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Pass the following data in the body API:

{
"testCaseName":"yourSimulationName",
"application":["applicationID-1", "applicationID-2"],
"circleRadius":"50",
"circleRadiusUnit":"km" or "miles",
"centerPoint":"lat,long",
"testGroup":["groupname-1","groupname-2"]
}

Send it. You will get a response message that the simulation has been created. Note down the simulation id for reference.


Update Simulation By Circle REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/circle/simulationID

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Enter any changes you want in the API

{
"testCaseName":"",
"application":["",]
"circleRadius":"",
"circleRadiusUnit":"km" or "miles",
"centerPoint":"lat,long",
"testGroup":["groupname-1","groupname-2"]
}

Send it. You will get a response message that the simulation has been updated.


Test Simulation By Circle REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/circle/test

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Pass the following data in the body to test:

{
"testcase_id":"simulationID",
"step":"0",
"application": ["applicationID"]
}

Layer

Via web application:

If you have the addresses of the locations where you want to test the simulation, you can do so by creating layers.

To create a layer, you'll need to upload the gpx file that contains your addresses, each in it's own column. The simulation will trigger at the locations specified by the lat-long values fetched by Google Maps API.
Each layer contains multiple points (your addresses) where the simulation can be tested and each layer simulation can have multiple layers.

Option to add a new layer is available while creating a new layer simulation. While uploading the gpx file, you'll also need to specify the radius around each point where the simulations will be tested.
You can also specify if you'd like to make your layer public to let others use your layers for their simulations. Therefore, it is advised to name your layers appropriately.

Via APIs:

Upload address CSV file:

https://apps.geolocationtech.com/api/v1/geosimulator/layers/file

Pass the apiKey in the header of the request. Then, upload your CSV file containing addresses.
Note down the uploaded file's url for reference.

Add Layer

https://apps.geolocationtech.com/api/v1/geosimulator/layers

Enter your gpx file's url that you just uploaded along with other details as given below.

{
"uploadFileURL":"youruploadFileURL",
"layername":"yourLayerName",
"radius":"1",
"circleRadiusUnit":"km" or "miles",
"type":"Public" or "Private"
}

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json". Note down the layer id for reference.

View Layer

https://apps.geolocationtech.com/api/v1/geosimulator/layers/layerID

Pass the apiKey in the header of the request.

Update Layer

https://apps.geolocationtech.com/api/v1/geosimulator/layers/layerID
{
"uploadFileURL":"youruploadFileURL",
"layername":"yourLayerName",
"radius":"1",
"circleRadiusUnit":"km" or "miles,
"type":"Public" or "Private"
}

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

List All Layers

https://apps.geolocationtech.com/api/v1/geosimulator/layers?

With filters

https://apps.geolocationtech.com/api/v1/geosimulator/layers?page=1&search=&filter=Public

Pass the apiKey in the header of the request.

Delete Layer

https://apps.geolocationtech.com/api/v1/geosimulator/layers/layerID

Pass the apiKey in the header of the request.


Add Simulation By Layer REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/layers

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Post the following data in body of the API:

{
"testCaseName" :"yourSimulationName",
"application" : ["applicationID-1","applicationID-2"],
"testGroup":["group1","group2"],
"layers":["layerID"]
}

Send it. You will get a response message that the simulation has been created.


Update Simulation By Layer REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/layers/layerID

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Post the following data in body of the API:

{
"testCaseName" :"",
"application" : [""],
"testGroup":["""],
"layers":["layerID"]
}

Send it. You will get a response message that the simulation has been updated.


Test Simulation By Layer REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/layers/test

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Post the following data in body of the API to test:

{
"testcase_id":"yourSimulationID",
"step":"0",
"application": ["applicationID"]
}

Groups

Groups basically allow you to define large scale simulations. Imagine this – you have an app that you want to test around all the Starbucks locations in NYC or you want to geofence your users around every CitiBank ATM around town. Instead of creating simulations and testing them individually, just assign them all to one group. This will allow you to test your app in all or any of those locations. In addition to this, you can also group various different places together. Say you have geofenced a bunch of businesses in Chelsea and you want to fire a trigger/alert if a user is near any of those businesses – just put them in a group and you are done. For situations where you want to fire an alert or a trigger only when a user is around a Bank of America location and a Starbucks – call the trigger with the option ‘all’. That’s it – that simple – no really!

Via APIs:

List All Groups REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/group

Pass the apiKey in the header of the request.


List Simulations For A Group

https://apps.geolocationtech.com/api/v1/geosimulator/group/groupID/simulations

Pass the apiKey in the header of the request.


Test simulations by a group

https://apps.geolocationtech.com/api/v1/geosimulator/group/test

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Post the following data in the body of the API to test

{
"group_id":"group-id",
"step":0,
"data":"0"
}

View, Update or Delete Application

Via web application:

From the Dashboard, you can view the list of all applications created by you. To view more details of a particular application, simply click on it. Once on the Application details page you can modify or delete that application from there.


Via APIs:

View Application REST API:

To view an application, pass the application id that you want to view in the API url and send it. In the response you will get corresponding details about the application id you have passed.

https://apps.geolocationtech.com/api/v1/geosimulator/application/applicationID

Pass the apiKey in the header of the request.


Update Application REST API:

To update the application, provide the application id in the url, then enter the details you want to update.

https://apps.geolocationtech.com/api/v1/geosimulator/application/applicationID

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Update any of the following data in "Update application" API to update

{
"name":"my name is changed",
"description":"Description is changed",
"os":"",
"os_version":"",
"iconUrl":""
}

List Applications REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/application

Pass the apiKey in the header of the request.


Delete Application REST API:

To delete the application - pass the application id in the "Delete application" API url and sumbit it. You will get a response message that your application has deleted.

https://apps.geolocationtech.com/api/v1/geosimulator/application/applicationID

Pass the apiKey in the header of the request.

View Simulations

Via web application:

From the Dashboard, click on 'View All Simulations" button to view all the simulations created by you.

Via APIs:

View Simulation REST API:

To view a simulation, pass the simulation id that you want to view in the API url and send it. In the response you will get corresponding details about the simulation id you have passed.

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/simulationID

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".


List All Simulations REST API:

This will get you all the simulations you have created.

https://apps.geolocationtech.com/api/v1/geosimulator/simulation

Pass the apiKey and the appKey in the header of the request. Also pass the "Content-Type" as "application/json".


Simulations By Application Id REST API:

https://apps.geolocationtech.com/api/v1/geosimulator/application/simulations/applicationID

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".


Delete Simulation REST API:

To delete the simulation - pass the simulation id in the "Delete simulation" API url and sumbit it. You will get a response message that your simulation has deleted.

https://apps.geolocationtech.com/api/v1/geosimulator/simulation/simulationID

Pass the apiKey in the header of the request.

Reset Password

Via web application:

To reset your password,

  1. Click on the 'Forgot Password' link on the Login page. Enter your registered email and you'll recieve an email with a token.
  2. Enter that token along with the registered email on the Login page to log in to GeoSimulator.
  3. Go to "My Profile" from the top-left drop-down. You can reset your password by clicking the 'Edit' button.

Via APIs:

Forgot Password REST API:

https://apps.geolocationtech.com/api/v1/forgot

Enter the email in the Forgot Password API and send it. You will receive an email with a token. In the login API, enter the username and in the password field, enter the token that you received in the email and post the data. You are logged in now.

{
"email":"email@example.com"
}

Once logged in, follow the web instructions to reset your password.


Reset API key

Via web application:

To reset your api key, go to your profile and click on the Reset API key button.


Update Profile REST API:

https://apps.geolocationtech.com/api/v1/user/userID

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".

Enter the details you'd like to update. Don't forget to update userID in the route.

{
"name":"yourName",
"username":"yourUserName",
"email":"email@example.com",
"company_name":"yourCompany",
"password":"yourPassword",
"password_confirmation":"confirmPassword",
"number":"yourNumber"
}

View User Profile REST API:

https://apps.geolocationtech.com/api/v1/user/userID

Pass the apiKey in the header of the request. Also pass the "Content-Type" as "application/json".