API Reference

Get last location

View Documentation

Create trip

View Documentation

Trip map view

View Documentation

List assets

View Documentation

Query tollbooth prices

View Documentation

Location History

View Documentation

Get Last Location

Fetch last known location of an asset or a group of assets that are registered on Numadic.

Method

GET

URL

https://api.numadic.com/location/asset

Required security headers

Key: Authentication
Value: Token for authentication

Required headers

aid=<16digitAlphaNumericAssetId>

To be used while requesting last location of single asset.

Unique asset ID provided by Numadic (compulsory if single)

gid=<16digitAlphaNumericGroupKey>

To be used while requesting last location of assets in one group

Unique group ID provided by Numadic to be used (compulsory if single)

gid=<16digitAlphaNumericGroupKey>&gid=<16digitAlphaNumericGroupKey>

To be used while requesting last location of single asset.

Unique asset ID provided by Numadic (compulsory if single)

Output Responses

Single Asset

200 Success
{
	"aid": "v2QkDLB7WVjNbkaO",
	"tis": 1500534187,
	"lat": 12.923237800598145,
	"lon": 79.88484191894531,
	"spd": 53,
	"ign": "B",
	"lic_plate_no": "KA01AA4863",
	"lname": "Chennai - Bengaluru Hwy, Thirumangalam, TN 602106"
}

Single Group

Code= 200 OK
{
	"gid": "2D8kpvl2bKgv71om",
	"assets": [
		{
			"lic_plate_no": "HR47C5007",
			"aid": "j5JkBanpjMdoR9XB",
			"ign": "A",
			"spd": 0,
			"lat": 28.17970848083496,
			"lon": 76.71168518066406,
			"tis": 1500534582,
			"lname": "DL - Jaipur Expy, HR 123401"
		}
	]
}

Multiple Groups

Code= 200 OK
[
	{
		"gid": "mEZkwM24rgVvy1pN",
		"assets": [
			{
				"aid": "y7DzghnjvBpONz4v",
				"ign": "A",
				"spd": 0,
				"lat": null,
				"lon": null,
				"tis": null
			},
			{
				"aid": "y7DzghnjvBpONz4v",
				"ign": "B",
				"spd": 16,
				"lat": 29.395374298095703,
				"lon": 76.78424072265625,
				"tis": 1489150812
			}
		]
	},
	{
		"gid": "mEZkwM24rgVvy1pN",
		"assets": [
			{
				"aid": "y7DzghnjvBpONz4v",
				"ign": "A",
				"spd": 0,
				"lat": null,
				"lon": null,
				"tis": null
			},
			{
				"aid": "y7DzghnjvBpONz4v",
				"ign": "B",
				"spd": 16,
				"lat": 29.395374298095703,
				"lon": 76.78424072265625,
				"tis": 1489150812
			}
		]
	}
]

Error Responses

Code: 403 Forbidden
Content: Forbidden

Curl Examples

Single Asset

curl -X GET 
'https://api.numadic.com/location/asset?aid=v2QkDLB7WVjNbkaO' 
-H 'authorization: <YOUR_API_KEY>'

Single Group

curl -X GET \
'https://api.numadic.com/location/asset?gid=2D8kpvl2bKgv71om' \
-H 'authorization: <YOUR_API_KEY>'

Notes

API Key short forms

aid:	Asset Unique Identifier
ign:	Ignition Status, A is for OFF, B is for ON
spd:	Speed of the vehicle in kmph
lat:	Geo Latitude
lon:	Geo Longitude
tis:	Epoch TImestamp (unix UTC)

Create trip

This API allows you to create a trip for assets that are registered with Numadic.

Method

POST

URL

https://api.numadic.com/client/v1/trip

Required security headers

Key: Authentication
Value: Token for authentication

Required body parameters

license_no:

License plate of the truck you wish to create the trip for

ext_tid:

External tripID, if you identify the trip on your platform using some ID, you can add that ID over here (Compulsory).

External tripID must be unique.

waypoints 
	lat, lon
	lat, lon
	lat, lon

The source and destination of the trip, has to be defined as lat,lon (both compulsory Fields).

stop_duration_in_minutes:

If the asset is to halt at this waypoint, you add time in minutes (Optional).

start_tis:

Start time of the trip. If not provided, the trip will start whenever the asset leaves the geo fence of the place or 15m radius of the starting lat,lon

seq:

Sequence of the waypoint; Eg: If the waypoint is 1st 2nd or 3rd;

lname:

Name of the location if you have any eg: Boca De Vaca, Panaji, 403509 (Optional).

Output Response Explanation

Output

200 Success
Numadic tripID

This is the Numadic trip ID. Tis has to be used every time you’re referencing the trip via any Numadic API.

External trip reference

This will be your company’s trip reference; eg: EZ1705A0123

ETA of Asset to start location (road distance and time)

Estimate time of arrival for the asset to reach the source of the trip.

Distance

Distance of current asset to the start location in meters.

Failure Conditions

Asset lic_plate missing

Error: Asset doesn’t exist with Numadic.

Asset lic_plate not shared with company (company calling the API)

Error: You do not have access to assign trips to this particular asset, please contact your account manager or help@numadic.com

Stat location validation failure

Error: Please enter correct data for start location lat,lon

End location validation failure

Error: Please enter correct data for end location lat,lon

External Trip Reference already exists

Error: External Trip Reference already exists, please change the name provided

Curl Examples

curl -X POST \
http://api.numadic.com/client/v1/trip \
-H 'authorization: <YOUR_API_KEY>' \
-H 'content-type': 'application/json' \
-d '{
	"license_no": "HR55X7387",
	"ext_tid": "sdfsdfvaryhwe5tvq",
	"waypoints": [
		{
			"lat": 27.564314295304225,
			"lon": 78.0524057397793,
			"tis": 12345689
		},
		{
			"lat": 28.92382,
			"lon": 79.19257,
			"tis": 12345689
		}
	]
}'

Output Responses

{
	"id": 16257,
	"ext_tid": "sdfsdfvaryhwe5tvq",
	"eta": 472,
	"distance": 1342451
}

Trip map view

This API allows you to view your trip on a map by directly loading the response via HTML

Method

GET

URL

https://api.numadic.com/client/v1/trip/map?tripID=XYZ

Required security headers

Key: Authentication
Value: Token for authentication

Required URL parameters

extID:string

External Trip ID.

tripID:string

Numadic’s Trip ID

Output Response

Output

200 Success

HTML Content with the following data

Trip Start Location
Trip End location
Trip trail polyline (from start to current position)
Current location of asset
Eta to destination
Distance covered
Estimated distance from start to destination

Failure Conditions

tripID type missing or invalid

Error : Error parsing type, please check input

tripID not authorized

Error : you are not authorized to view data for this tripID

Curl Examples

curl -X GET \
'https://api.numadic.com/client/v1/trip/map?tripID=16257' \
-H 'authorization: <YOUR_API_KEY>'

List assets

This API allows you to get a list of all your assets which are registered with Numadic.

Method

GET

URL

https://api.numadic.com/client/v1/assets

Required security headers

Key: Authentication
Value: Token for authentication

Required URL parameters

extID='yes/no'

All your assets belong to particular groups. If this is enabled, the output will be in a group hierarchy.

&start_tis= 
&end_tis=

You can mention Start timestamp and end timestamp to get a list of assets that were adding during that time frame.

Output Response Explanation

Output

200 Success

JSON array parameters

lic_plate_no
Eid

ID of Nubot attached to asset

Asset_id

Numadic Asset ID

added_tis

Epoch timestamp of asset added to Numadic

Status

If the Asset is Live or not.

Failure Conditions

Time range of adding

You have added an invalid time bound, please correct the time-bounds

Curl Examples

curl -X GET \
'http://api.numadic.com/client/v1/assets?byGroup=yes' \
-H 'authorization: <YOUR_API_KEY>'

Output Responses

{
	"group_id": 34,
	"assets": [
		{
			"nubot_id": "IT1703C00311",
			"vehicle_license": "HR47C5007",
			"added_tis": 1499929307,
			"status": true
		}
	]
}

Query Tollbooth Prices

This API allows you to get the cost of toll by providing your start and stop location or getting tollbooths that are in a vicinity of a particular point.

Method

GET

URL

https://api.numadic.com/client/v1/tollbooth

Required security headers

Key: Authentication
Value: Token for authentication

Required URL parameters

  1. Location or Tollbooth name (any one of the below three)
    1. Source
      slat - latitude
      slon - longitude
      
    2. Toll booth name (If lat,lon cannot be provided, compulsory if source and/or destination is not provided)
      Name - name of the tollbooth
      
    3. Source and destination
      slat - latitude
      slon - longitude
      dlat - latitude
      dlon - longitude
      
  2. Vehicle Type (compulsory)
    1. vtype
      vtype - car, jeep, van, lmv, lcv, bus, truck, 2axle, 3axle, 4axle, 5axle, 6axle, 7axle, hcm, eme
      

Output Response Explanation

Output

200 Success

JSON array structured in the following format

vehicleType

	Tollbooth ID - ID (Internal/External)
		Tollbooth name - Name of the tollbooth
		Tollbooth location - lat,lon of the tollbooth
		Tollbooth state - state of the tollbooth
		Tollbooth price - Price in INR (single/return/monthly)

	Tollbooth ID - ID (Internal/External)
		Tollbooth name - Name of the tollbooth
		Tollbooth location - lat,lon of the tollbooth
		Tollbooth state - state of the tollbooth
		Tollbooth price - Price in INR (single/return/monthly)

Failure Conditions

Lat,Lon validation failure

Please enter valid location for source/destination

Tollbooth not found

No tollbooth found within radius for given location

Vehicle Type validation failure

Please enter correct option for vehicle type

Examples

  1. Source only
    https://api.numadic.com/client/v1/tollbooth?slat=24.620102&slon=77.261808&vtype=van
  2. Source and destination
    https://api.numadic.com/client/v1/tollbooth?slat=24.620102&slon=77.261808&dlat=24.669293&dlon=77.304628&vtype=van
  3. Tollbooth name
    https://api.numadic.com/client/v1/tollbooth?name=Shabaz&vtype=van

Curl Examples

curl -X GET   'http://api.numadic.com/client/v1/tollbooth?slat=24.620102&slon=77.261808&vtype=van' 
-H 'authorization: <INSERT_KEY>'

Output Response

{
	"vehicleType": "van",
	"tollbooths": [
		{
			"name": "Guna Bypass",
			"lat": 24.6203723314102,
			"lon": 77.2614656573198,
			"fees": [
				{
					"singleJourney": "15.00",
					"returnJourney": "20.00",
					"monthlyPass": "NA"
				}
			],
			"state": "Madhya Pradesh"
		}
	]
}

Location History

This API allows you to get last known location history for your asset or assets belonging to a group.

Limits Note

1 Asset - 48 hrs
10 Assets - 12 hrs
20 Assets - 6 hrs
50 Assets - 3hrs

For more than 100 Assets, please contact sales@nuamdic.com

Method

GET

URL

https://api.numadic.com/client/v1/location/asset/history

Required security headers

Key: Authentication
Value: Token for authentication

Required URL parameters

  1. gid: number
    1. group id the asset/assets belong to
    OR
    licno : string
    1. Vehicle license plate number to be searched
  2. stis: number
    1. Start timestamp.
  3. etis: number
    1. End timestamp

Output Response Explanation

Output

200 Success

JSON array structured in the following format

requestedTime - Timestamp of when the request was made by the user

start_tis, stop_tis - Start and stop timestamps provided by user

location_data
	lic_plate_no - License plate provided by user
	gid - List of groups the asset belongs to 
	segments - Location trail of the asset

Failure Conditions

Asset not found on Numadic

"error": "Asset not found"

Group ID not found on Numadic

"error": "Group id not found"

User not authorized to view asset / group

"error": "You don’t have permission to access this group/asset"

If gid and licno is entered

"error": "Please gid or licno"

Invalid time range

"error": "Please enter time range for stis & etis"

Asset limit exceeded for the time frame

"error": "Exceeded the asset limit for the requested timeframe"

Exceeded or invalid time range

"error": "Invalid/Exceeded requested timeframe"

Curl Examples

curl -X GET \
  'http://api.numadic.com/client/v1/location/history?gid=2&stis=1504412950&etis=1504448950' \
  -H 'authorization: <PASTE YOUR TOKEN HERE>’

Output Response

{
    "requestedTime": 1504769380,
    "start_tis": 1504412950,
    "stop_tis": 1504448950,
    "location_data": [
        {
            "lic_plate_no": "MH09CA1236",
            "gid": [
                2
            ],
            "segments": [
                "1504448152,18.702726,73.849593,0,A",
                "1504448107,18.702726,73.849593,0,A"
            ]
        }
    ]
}