Skip to content

Quick start

In this guide you will go through the required steps to integrate Astara Connect in your own systems or platforms.

1.- Creating an account

In order to start using our APIs, you will need to create an account. Once you have registered, come back to this page to continue.

Authentication methods

Astara Connect offers you two main methods for authenticating:

  • Your current user (using your email and password)
  • An API token created for your organization.

With email and password

By default, Astara Connect allows you to authenticate your user using the email and password that you have used to register in the site.

You can login using the endpoint:

1
POST https://api.astaraconnect.com/v1/users/login

With a payload like this:

1
{"email":"youremail","password":"password"}

You will get a JWT token that you will have to use within your API calls to authenticate:

1
Authentication: Bearer <token>

With an API token

If you want to avoid using your own credentials, you can create a token that will identify the organization instead of you.

For creating the token, use the following endpoint:

1
POST https://api-staging.astaraconnect.com/v1/organizations/create-api-key

This will return an API key that you can use to authenticate your API calls using the following HEADER in your calls:

1
X-BOTON-APIKEY: your-key

Warning

You cannot recover the key. If you don't save it the system cannot show it to you as is fully encrypted. You will need to generate a new key, and replace it.

2.- Registering your first tracker

Once you have an account, you will need to register a tracker so you can start getting geo-data that Astara Connect will process and give you insights.

A tracker is a device that is connected to a vehicle (or moving object) that will be sending at least the following information:

  • Latitude.
  • Longitude.
  • Timestamp.

In order to register it, you will need to find out the default group (organization is named right now but will be changed into group in coming weeks) that your account has access to.

1
GET /v1/organizations/

There you will have the OIDs and extra data of the groups where you can register a tracker to. Pick one, and save the OID for using it later on.

Now, register the tracker:

1
POST /v1/trackers/register

You will have to send a JSON payload similar to this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "tracker_id"="359632104952350",
    "provider"="astrata",
    "type"="obd",
    "vehicle_type"="car",
    "organization_oid"="organization_oid",
    "object_id"={
        "vin": "WF0AXXWPMAJB43745",
        "license_plate": "6666KKK",
        "make": "Honda",
        "model": "Civic"
    }
}

Info

The object_id can store any metadata from your vehicle. By default, we recognize some keys like license_plate, make, model, version, vin, ean, serial_number as those are common fields within the cars, vans, bikes, kickscooters and trucks. But you can store as much information as you want.

To finish the tracker registration, you will need to launch the validation procedure. It's a security step that lets us know that you have the rights to access the tracker data. 

1
POST /v1/trackers/validate
The validation procedure could work on a synchronous or asynchronous way. To find out the results, you can look in the tracker's validation status field. As usual and if everything goes well the status will be pending for data. It means that the tracker was registered successfully and the system is waiting to receive data from it. Once we have obtained any positioning data of the tracker, the whole connection process would be completed (final status reached: connected).

3.- Getting telemetrics data from your tracker

Now that you have the tracker, as soon as the tracker is validated by the system, you will be able to start getting telemetrics data from it like its last position. In order to check if the tracker is receiving data properly, get the tracker and check its status value. If its value is true, then, your tracker is fully working within Astara Connect:

1
GET /v1/trackers/{tracker_oid}

And it will return something like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "foreign_tracker_id": "string",
  "end_date": "2021-08-13T09:34:42.092Z",
  "vehicle_type": "string",
  "tracker_id": "string",
  "oid": "string",
  "user_oid": "string",
  "type": "string",
  "provider": "string",
  "heartbeat": "2021-08-13T09:34:42.092Z",
  "validation_status": "string",
  "organization_oid": "string",
  "start_date": "2021-08-13T09:34:42.092Z",
  "object_id": {}
}

Then, with that tracker's oid you can get its last saved position:

1
GET /v1/telemetrics/{tracker_oid}/position

And that will give you something similar to this:

1
2
3
4
5
{
  "longitude": float,
  "latitude": float,
  "ts": "2021-08-13T09:33:48.465Z"
}
Astara Connect provides many more endpoints for the telemetrics, like computed trips, moving-stopped trackers, etc. Check the telemetrics section as well as all our endpoints.

4.- Next steps

This guide has covered the main basics, for setting you up quickly. Now we recommend you to explore our documentation and get an idea about what Astara Connect can offer you. We recommend you to read the following sections of our documentation: