KartaView API (3.0)

KartaView is a free and open platform for street level imagery.

Introduction

This document serves as a comprehensive guide for users who are interested in harnessing the capabilities of the KartaView API to utilize imagery .

How to use KartaView API

KartaView functions on the basis of organizations with initial user authentication being a prerequisite. A unique token is then passed within each API request. This token check is crucial as it allows the system to verify the organization permissions associated with the user, ensuring appropriate access to required resources. The steps to utilize KartaView API are outlined below:

Step 1: User Authentication We first need to authorize a 'userLogin' operation. we can use google login and then login to our system userLogin.

Step 2: Save Access Token Upon successful login, an access_token will be generated and returned to you by the API .

Step 3: Usage in API Requests Following successful user authentication and token storage, this access_token must then be included in the header of subsequent API requests. .

API Resources

Version 3.0 of the KartaView API is designed based on Resource Oriented Architecture(ROA). A resource is defined as an object with a type, associated data, relationships to other resources, and a set of methods that you can operate with .

Available resources

Currently available resources are:

Pagination

Requests that will return a large collection of data can be paginated for faster response. Options:

itemsPerPage
page

For example, https://karta-gateway.geo.azure.myteksi.net/view/api/2.0/photo/?itemsPerPage=10&page=2 will output photo result set of 10 records from the second page.

Ordering

Request results can be ordered in two ways. Options:

orderBy
orderDirection

For example, https://karta-gateway.geo.azure.myteksi.net/view/api/2.0/photo/?orderBy=id&orderDirection=DESC will output photo result ordered based on photo id column, in a descending manner.

If orderDirection is not specified, then the default value of ASC will be taken into consideration.

Join

To simplify requests and enrich response with data, the JOIN query parameter can bring additional data without the need for another request.

For example,https://karta-gateway.geo.azure.myteksi.net/view/api/2.0/photo/2133?join=user will output the sequence resource details and associated user joined resource.

Response

JSON is the default response format.

Sequence

A sequence is a collection of photos captured continuously by an KartaView user. Available connected-resources: attachments, rawdatas, photos, videos.

Available joining resources for : photo(first photo of the sequence used for thumbnails), user(owner of the sequence).
Available joining resources for one resource request: Photo list .
Restricted access on GET list if there isn't at least one query parameter provided from the following: id, idInterval, region, startDate, userId, tLeft, bRight, withPhotos.

Sequence details .

query Parameters

id required	number <integer> Unique identifier of an entity, query for a set of ids is possible, separated by `,`. For example: id=545,546,547
platform required	string Default: null Example: platform=web The platform request this API , we can just pass web in this case

header Parameters

X-Karta-Token

required

string

Example: 2bdf59f2-3699-4544-8c49-e8ca6516bf51

Auth token is required for this action.

Responses

200

Success

400

Bad Request

404

Success, resource not found

500

Internal Server Error

get /view/api/details

https://karta-gateway.geo.azure.myteksi.net/view/api/details

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"status":
{
- "apiCode": 600,
- "apiMessage": "The request has been processed without incidents",
- "httpCode": 200,
- "httpMessage": "Success",
- "executionTime": 0.0946
},
"osv":
{
- "date_added": "Jan 18, 2021",
- "platform": "KartaCam360Lite",
- "user": "driver-4-bumi",
- "user_id": "124",
- "meta_data_filename": "storage106/files/photo/2024/2/22/",
- "address": "404 East Stewart Avenue, Las Vegas, Nevada 89101, United States",
- "country_code": "US",
- "reviewed": "0",
- "distance": "105.93",
- "changed": "120.48",
- "obd_info": "OBD2, U480 Obd2 CAN BUS & Engine Code Reader",
- "count_active_photos": "500",
- "recognitions": "Recognition in Community Awards 2021",
- "client_total": "1500",
- "is_rotating": "false",
- "cameraParameters":
  [
  - {
    "fNumber": "2.2",
    "fLen": "4.15",
    "vFOV": "58.04",
    "vZF": "153.0",
    "aperture": "2.200000047683716"
    }
  ],
- "deviceName": "KartaCam360LiteV1",
- "owner": "false",
- "upload_history":
  {
  - "id": "id=123",
  - "sequence_id": "id=123",
  - "user_id": "user_id=124",
  - "user_category": "user_category=REGULAR",
  - "distance": "105.93",
  - "has_obd": "has_obd=N",
  - "date_updated": "2016-04-16 09:00:45"
  },
- "photos":
  [
  - {
    "id": 112,
    "org_code": "GRAB",
    "sequenceId": 213,
    "sequenceIndex": 1000,
    "lat": "37.649595",
    "lng": "-122.097050",
    "fileName": "16ada_56cc3645da3c9.jpeg",
    "name": "storage103/files/photo/2021/1/18/proc/2369247_477af_600607aca0c3a.jpg",
    "lth_name": "storage103/files/photo/2021/1/18/lth/2369247_477af_600607aca0c3a.jpg",
    "th_name": "storage103/files/photo/2021/1/18/th/2369247_477af_600607aca0c3a.jpg",
    "path": "2021/1/18",
    "dateAdded": "2016-04-15 23:05:32",
    "timestamp": "1611007918",
    "way_id": "140474913",
    "match_lat": "46.781887054443360",
    "match_lng": "23.688762664794922",
    "heading": "161.082520",
    "headers": "161.082520",
    "gpsAccuracy": "10.000",
    "storage": "storage1",
    "shotDate": "2016-04-16 09:00:45",
    "projection": "PLANE",
    "filed_of_view": "360",
    "is_unwrapped": "0",
    "unwrap_version": "2",
    "width": "2592",
    "height": "2592",
    "cameraParameters":
    [
    {
    "fNumber": "2.2",
    "fLen": "4.15",
    "vFOV": "58.04",
    "vZF": "153.0",
    "aperture": "2.200000047683716"
    }
    ],
    "hasDepth": "false"
    }
  ]
}

}

Get map matched tracks data with different output. Available path extensions: json, jsoncanvas, png, geojson, topojson

path Parameters

tileX required	string Value calculated based on latitude.
tileY required	string Value calculated based on longitude.
tileZ required	string Value representing zoom level.

header Parameters

X-Karta-Token

required

string

Example: 2bdf59f2-3699-4544-8c49-e8ca6516bf51

Auth token is required for this action.

Responses

200

Success

400

Bad Request

404

Success, resource not found

500

Internal Server Error

get /view/api/tiles/{tileX}/{tileY}/{tileZ}.json

https://karta-gateway.geo.azure.myteksi.net/view/api/tiles/{tileX}/{tileY}/{tileZ}.json

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"status":
{
- "apiCode": 600,
- "apiMessage": "The request has been processed without incidents",
- "httpCode": 200,
- "httpMessage": "Success",
- "executionTime": 0.0946
},
"result":
{
- "lines":
  {
  - "tracks":
    [
    {
    "lat": "37.649595",
    "lng": "-122.097050"
    }
    ],
  - "coverage": 0,
  - "matched": 0
  }
}

}

Photo

Geo-tagged images, part of a sequence.

Restricted access on GET list if there isn't at least one query parameter provided from the following: id, idInterval, sequenceId, lat and lng.

Get the details of a photo.

path Parameters

required

string

Unique identifier of an entity.

query Parameters

join	string Default: "null" Example: join=user,sequence Join resources to bring extra details about another resource, available joinable resource: rawdata, video, user, sequence.

header Parameters

X-Karta-Token

required

string

Example: 2bdf59f2-3699-4544-8c49-e8ca6516bf51

Auth token is required for this action.

Responses

200

Success

400

Bad Request

404

Success, resource not found

500

Internal Server Error

get /view/api/2.0/photo/{id}

https://karta-gateway.geo.azure.myteksi.net/view/api/2.0/photo/{id}

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"status":
{
- "apiCode": 600,
- "apiMessage": "The request has been processed without incidents",
- "httpCode": 200,
- "httpMessage": "Success",
- "executionTime": 0.0946
},
"result":
{
- "data":
  {
  - "id": 112,
  - "sequenceId": 213,
  - "videoId": 555,
  - "rawDataId": 112,
  - "videoIndex": 20,
  - "sequenceIndex": 1000,
  - "dateAdded": "2016-04-15 23:05:32",
  - "dateProcessed": "2016-04-16 09:00:45",
  - "name": "16ada_56cc3645da3c9.jpeg",
  - "lat": "37.649595",
  - "lng": "-122.097050",
  - "heading": "161.082520",
  - "visibility": "private",
  - "autoImgProcessingStatus": "FINISHED",
  - "status": "deleted",
  - "gpsAccuracy": "10.000",
  - "distance": "10.000",
  - "autoImgProcessingResult": "ORIGINAL",
  - "matchLat": "46.781887054443360",
  - "matchLng": "23.688762664794922",
  - "matchSegmentId": "23.688762664794922",
  - "from": "30074863",
  - "to": "186970534",
  - "wayId": "140474913",
  - "storage": "storage1",
  - "width": "2592",
  - "cameraParameters":
    [
    {
    "fNumber": "2.2",
    "fLen": "4.15",
    "vFOV": "58.04",
    "vZF": "153.0",
    "aperture": "2.200000047683716"
    }
    ],
  - "height": "2592",
  - "filepath": "2018/9/4/{{sizeprefix}}/1286317_c3307_42f.jpg",
  - "filepathLTh": "2018/9/4/{{sizeprefix}}/1286317_c3307_42f.jpg",
  - "filepathProc": "2018/9/4/{{sizeprefix}}/1286317_c3307_42f.jpg",
  - "filepathTh": "2018/9/4/{{sizeprefix}}/1286317_c3307_42f.jpg",
  - "fileurl": "",
  - "fileurlLTh": "",
  - "fileurlProc": "",
  - "fileurlTh": "",
  - "imageProcUrl": "",
  - "imageLthUrl": "",
  - "imageThUrl": "",
  - "projection": "PLANE",
  - "imagePartProjection": "DUAL_FISHEYE",
  - "fieldOfView": "180.00",
  - "shotDate": "2016-04-16 09:00:45",
  - "hasObd": "0",
  - "isWrapped": "1",
  - "isUnwrapped": "0",
  - "projectionYaw": "180",
  - "wrapVersion": "1",
  - "unwrapVersion": "0"
  }
}

}

Retrieve photos.

query Parameters

id	number <integer> Unique identifier of an entity, query for a set of ids is possible, separated by `,`. For example: id=545,546,547
idInterval	number <integer> Unique identifier of an entity, query for an interval of ids is possible, separated by `-`. For example: idInterval=545-547
page	number <integer> Retrieve data from the desired page number.
itemsPerPage	number <integer> Default: 40 Example: itemsPerPage=10 Number of items on a page.
orderBy	string Example: orderBy=dateAdded Sorting by a particular field, see full list below in the response example section.
orderDirection	string Enum: "asc" "desc" Sorting direction.
units	string Default: "metric" Enum: "metric" "imperial" The type of the distance measurement.
join	string Default: "null" Example: join=user,sequence Join resources to bring extra details about another resource, available joinable resource: rawdata, video, user, sequence.
sequenceId	number <integer> Example: sequenceId=112 Unique identifier representing a specific sequence.
sequenceIndex	number <integer> Identifier representing a specific image index.
searchSequenceType	string Enum: "photo" "video" "vdb" Example: searchSequenceType=vdb Type of the sequence. Used only for findNearbyPhotos functionality.
searchPlatform	string Enum: "ios" "android" "waylens" "gopro" "other" Example: searchPlatform=ios The platform of the device that recorded the file. Used only for findNearbyPhotos functionality.
searchFieldOfView	string Enum: "plane" "180" "360" "dual_fisheye" Example: searchFieldOfView=180 The field of view type. Used only for findNearbyPhotos functionality.
userId	string Example: userId=30191,250315 Unique identifier of an user entity.
videoIndex	number <integer> Identifier representing a specific video index.
projection	string Enum: "PLANE" "CYLINDER" "SPHERE" "FISHEYE" "CUBE" Example: projection=PLANE The distortion type of the photo.
projectionYaw	string <number> Example: projectionYaw=180 The projection on yaw axis, horizontal rotation in degrees, min -180, max 180.
fieldOfView	string Default: null Enum: "plane" "180" "360" "dual_fisheye" Example: fieldOfView=plane The field of view type.
lat	string <decimal(9,6)> Latitude coordinates of the photo.
lng	string <decimal(9,6)> Latitude coordinates of the photo.
radius	string Controls the size of the edges that can be enhanced, where a smaller radius enhances smaller-scale detail.
zoomLevel	string Value representing zoom level. Default value is 18.

header Parameters

X-Karta-Token

required

string

Example: 2bdf59f2-3699-4544-8c49-e8ca6516bf51

Auth token is required for this action.

Responses

200

Success

400

Bad Request

404

Success, resource not found

500

Internal Server Error

get /view/api/2.0/photo/

https://karta-gateway.geo.azure.myteksi.net/view/api/2.0/photo/

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"status":
{
- "apiCode": 600,
- "apiMessage": "The request has been processed without incidents",
- "httpCode": 200,
- "httpMessage": "Success",
- "executionTime": 0.0946
},
"result":
{
- "data":
  [
  - {
    "id": 112,
    "sequenceId": 213,
    "videoId": 555,
    "rawDataId": 112,
    "videoIndex": 20,
    "sequenceIndex": 1000,
    "dateAdded": "2016-04-15 23:05:32",
    "dateProcessed": "2016-04-16 09:00:45",
    "name": "16ada_56cc3645da3c9.jpeg",
    "lat": "37.649595",
    "lng": "-122.097050",
    "heading": "161.082520",
    "visibility": "private",
    "autoImgProcessingStatus": "FINISHED",
    "status": "deleted",
    "gpsAccuracy": "10.000",
    "distance": "10.000",
    "autoImgProcessingResult": "ORIGINAL",
    "matchLat": "46.781887054443360",
    "matchLng": "23.688762664794922",
    "matchSegmentId": "23.688762664794922",
    "from": "30074863",
    "to": "186970534",
    "wayId": "140474913",
    "storage": "storage1",
    "width": "2592",
    "cameraParameters":
    [
    {
    "fNumber": "2.2",
    "fLen": "4.15",
    "vFOV": "58.04",
    "vZF": "153.0",
    "aperture": "2.200000047683716"
    }
    ],
    "height": "2592",
    "filepath": "2018/9/4/{{sizeprefix}}/1286317_c3307_42f.jpg",
    "filepathLTh": "2018/9/4/{{sizeprefix}}/1286317_c3307_42f.jpg",
    "filepathProc": "2018/9/4/{{sizeprefix}}/1286317_c3307_42f.jpg",
    "filepathTh": "2018/9/4/{{sizeprefix}}/1286317_c3307_42f.jpg",
    "fileurl": "",
    "fileurlLTh": "",
    "fileurlProc": "",
    "fileurlTh": "",
    "imageProcUrl": "",
    "imageLthUrl": "",
    "imageThUrl": "",
    "projection": "PLANE",
    "imagePartProjection": "DUAL_FISHEYE",
    "fieldOfView": "180.00",
    "shotDate": "2016-04-16 09:00:45",
    "hasObd": "0",
    "isWrapped": "1",
    "isUnwrapped": "0",
    "projectionYaw": "180",
    "wrapVersion": "1",
    "unwrapVersion": "0"
    }
  ],
- "hasMoreData": false
}

}

User

KartaView contributor, owner of the sequence data.

User login in KartaView .

query Parameters

service required	string Example: service=karta-view In karta B2B login api , we need pass service we use, we can just pass karta-view in this case
oauth_provider required	string Example: oauth_provider=google Is about what oauth provider we use , we can just input google .
oauth_token required	string Example: oauth_token=ya29.a0Ad52N38tQIzl7Zb6KT_3OpVcuioaCYOsU1AtSXKbu7vVYy1nupzJRess_8o We got from google login .

Responses

200

Success

400

Bad Request

500

InternalError

get /id/service/v1/login

https://karta-gateway.geo.azure.myteksi.net/id/service/v1/login

Response samples

Content type

application/json

Copy

Expand all Collapse all

{

"user_info":
{
- "user_id": "123456789",
- "user_email": "user@gmail.com",
- "org_code": "ORG123",
- "status": "ACTIVE",
- "role_list":
  [
  - "Admin",
  - "User"
  ],
- "org_name": "GRAB",
- "oauth_type": "google",
- "organizations":
  [
  - {
    "name": "GRAB Organization",
    "code": "GRAB"
    }
  ],
- "username": "User123",
- "kv_user_id": "789456123",
- "jarvis_user_id": "456123789"
},
"access_token": "2bdf59f2-3699-4544-8c49-e8ca6516bf51",
"refresh_token": "57415270-7f6d-4fc1-bb05-1c5f715f9964"

}