NAV Navbar
javascript shell

Introduction

const CA = require('civil-analytics-js');

let ca = new CA('e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855');

This is the documentation for the Cvil Analytics API. You can use this SDK to upload videos and start extractions.

Videos

Upload Video

POST /api/v1/videos/upload

const fs = require('fs')

ca.videos.upload({
    group_id: 'a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b',
    video: fs.readFileSync('./video.mp4'),
}).then((video) => {
  console.log(video);
})
curl 'https://civil-analytics.ideea.io/api/v1/videos/upload' \
  -X POST \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache' \
  -F group_id=a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b \
  -F video=@/tmp/video.mp4

Response

{
    "data": {
        "id": "031380e4-c221-4720-85a4-c9e2a4ab72eb",
        "group_id": "a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b",
        "uploaded_by": "46438def-9a34-4466-ba4c-46438def7d7f",
        "type": "upload",
        "name": "video.mp4",
        "url": "https://civilanalyics-videos.sfo2.digitaloceanspaces.com/031380e4-c221-4720-85a4-c9e2a4ab72eb.mp4",
        "thumbnail": "https://civilanalyics-thumbnails.sfo2.digitaloceanspaces.com/031380e4-c221-4720-85a4-c9e2a4ab72eb.png",
        "created_at": "2019-10-02T16:12:14.495Z",
        "updated_at": "2019-10-02T16:12:14.495Z",
        "deleted_at": null
    },
    "meta": {},
    "status": "ok"
}

To upload a new video make a post request to /api/v1/videos/upload. This will create the video with the provided data.

HTTP Endpoint

POST https://civil-analytics.ideea.io/api/v1/videos/create

Request Payload

Parameter Required Description
group_id true The group ID that this video will belong to
video true The video file
name false Name of the video

Create Video

POST /api/v1/videos/create

ca.videos.create({
    group_id: 'a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b',
    name: 'The Office',
    url: 'https://example.com/public-video.mp4',
}).then((video) => {
  console.log(video);
})
curl 'https://civil-analytics.ideea.io/api/v1/videos/create' \
  -X POST \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache' \
  -F group_id=a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b \
  -F url='https://example.com/public-video.mp4'

Response

{
    "data": {
        "id": "9c56205e-c669-4e81-ab74-83d8142f0d57",
        "group_id": "a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b",
        "uploaded_by": "46438def-9a34-4466-ba4c-46438def7d7f",
        "type": "link",
        "name": "video.mp4",
        "url": "https://example.com/public-video.mp4",
        "thumbnail": "https://civilanalyics-thumbnails.sfo2.digitaloceanspaces.com/9c56205e-c669-4e81-ab74-83d8142f0d57.png",
        "created_at": "2019-10-02T16:12:14.495Z",
        "updated_at": "2019-10-02T16:12:14.495Z",
        "deleted_at": null
    },
    "meta": {},
    "status": "ok"
}

To create a new video make a post request to /api/v1/video/create. This will create the video with the provided data.

HTTP Endpoint

POST https://civil-analytics.ideea.io/api/v1/videos/create

Request Payload

Parameter Required Description
group_id true The group ID that this video will belong to
url true A link to a publicly publicly video
name false Name of the video

Get Videos By Group ID

GET /api/v1/videos/group/{group_id}

ca.videos.getByGroupID('a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b')
.then((videos) => {
  console.log(videos);
})
curl 'https://civil-analytics.ideea.io/api/v1/videos/group/a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b' \
  -X GET \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

{
    "data": [
        {
            "id": "9c56205e-c669-4e81-ab74-83d8142f0d57",
            "group_id": "a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b",
            "uploaded_by": "46438def-9a34-4466-ba4c-46438def7d7f",
            "type": "link",
            "name": "video.mp4",
            "url": "https://example.com/public-video.mp4",
            "thumbnail": "https://civilanalyics-thumbnails.sfo2.digitaloceanspaces.com/9c56205e-c669-4e81-ab74-83d8142f0d57.png",
            "created_at": "2019-10-02T16:12:14.495Z",
            "updated_at": "2019-10-02T16:12:14.495Z",
            "deleted_at": null
        }
    ],
    "meta": {},
    "status": "ok"
}

This endpoint returns all of the group's videos

HTTP Endpoint

GET https://civil-analytics.ideea.io/api/v1/videos/group/{group_id}

Get Video By ID

GET /api/v1/videos/{video_id}

ca.videos.get('9c56205e-c669-4e81-ab74-83d8142f0d57').then((video) => {
  console.log(video);
})
curl 'https://civil-analytics.ideea.io/api/v1/videos/9c56205e-c669-4e81-ab74-83d8142f0d57' \
  -X GET \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

{
    "data": {
        "id": "9c56205e-c669-4e81-ab74-83d8142f0d57",
        "group_id": "a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b",
        "uploaded_by": "46438def-9a34-4466-ba4c-46438def7d7f",
        "type": "link",
        "name": "video.mp4",
        "url": "https://example.com/public-video.mp4",
        "thumbnail": "https://civilanalyics-thumbnails.sfo2.digitaloceanspaces.com/9c56205e-c669-4e81-ab74-83d8142f0d57.png",
        "created_at": "2019-10-02T16:12:14.495Z",
        "updated_at": "2019-10-02T16:12:14.495Z",
        "deleted_at": null
    },
    "meta": {},
    "status": "ok"
}

This endpoint will retrun a video by it's ID

HTTP Endpoint

GET https://civil-analytics.ideea.io/api/v1/video/{video_id}

Delete a Video

DELETE /api/v1/videos/{video_id}/delete

ca.videos.delete('2e79a2df-25e7-4a61-8e8e-f29bb96a3550')
.then((deletedVideo) => {
  console.log(deletedVideo);
})
curl 'https://civil-analytics.ideea.local/api/v1/videos/2e79a2df-25e7-4a61-8e8e-f29bb96a3550/delete' \
  -X DELETE \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

{
    "data": {
        "id": "f8284c75-74d6-4fcb-b2ff-608a9db01c28",
    },
    "meta": {},
    "status": "ok"
}

To delete a video make a DELETE request to /videos/{video_id}/delete

HTTP Endpoint

DELETE https://civil-analytics.ideea.io/api/v1/videos/{video_id}/delete

Extractions

Create Extraction

POST /api/v1/extractions/create

ca.extractions.create({
    group_id: 'a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b',
    video_id: '9c56205e-c669-4e81-ab74-83d8142f0d57',
    confidence_level: 0.5,
    callback_url: 'https://example.com/callback',
    model: 'uk-road-signs',
}).then((extraction) => {
  console.log(extraction);
})
curl 'https://civil-analytics.ideea.io/api/v1/extractions/create' \
  -X POST \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'cache-control: no-cache' \
  -F group_id=a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b \
  -F video_id=9c56205e-c669-4e81-ab74-83d8142f0d57 \
  -F confidence_level=0.5 \
  -F callback_url=https://example.com/callback \
  -F model=uk-road-signs

Response

{
    "data": {
        "id": "42036b7e-6fd8-43af-a06b-f7d32dd9889f",
        "group_id": "2f8fdea3-b875-4926-90c8-5a1b11b818c8",
        "video_id": "9c56205e-c669-4e81-ab74-83d8142f0d57",
        "created_by": "aaaaaaaa-9a34-4466-ba4c-46438def7d7f",
        "model": "uk-sign",
        "status": "pending",
        "confidence_level": 0.1,
        "callback_url": "https://example.com/callback",
        "processing_time": 0,
        "charge_id": null,
        "output_video_url": null,
        "output_json_url": null,
        "updated_at": "2019-10-02T17:26:48.098Z",
        "created_at": "2019-10-02T17:26:48.098Z"
    },
    "meta": {},
    "status": "ok"
}

To create a new extraction make a post request to /api/v1/extractions/create. This will create an extraction with the provided data.

HTTP Endpoint

POST https://civil-analytics.ideea.io/api/v1/extractions/create

Request Payload

Parameter Required Description
group_id true The group ID that this video will belong to
video_id true The video to process
model true The detection model to use
confidence_level true Detection confidence level
callback_url false Callback URL when complete

Get Extractions By Group ID

GET /api/v1/extractions/group/{group_id}

ca.extractions.getByGroupID('a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b')
.then((extractions) => {
  console.log(extractions);
})
curl 'https://civil-analytics.ideea.io/api/v1/extractions/group/a0ffedbb-ff29-5138-9b5d-cd1f6ae3bc6b' \
  -X GET \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

{
    "data": [
        {
            "id": "42036b7e-6fd8-43af-a06b-f7d32dd9889f",
            "group_id": "2f8fdea3-b875-4926-90c8-5a1b11b818c8",
            "video_id": "9c56205e-c669-4e81-ab74-83d8142f0d57",
            "created_by": "aaaaaaaa-9a34-4466-ba4c-46438def7d7f",
            "model": "uk-sign",
            "status": "pending",
            "confidence_level": 0.1,
            "callback_url": "https://example.com/callback",
            "processing_time": 0,
            "charge_id": null,
            "output_video_url": null,
            "output_json_url": null,
            "updated_at": "2019-10-02T17:26:48.098Z",
            "created_at": "2019-10-02T17:26:48.098Z"
        }
    ],
    "meta": {},
    "status": "ok"
}

This endpoint returns all of the group's extractions

HTTP Endpoint

GET https://civil-analytics.ideea.io/api/v1/extractions/group/{group_id}

Get Video By ID

GET /api/v1/extractions/{video_id}

ca.extractions.get('9c56205e-c669-4e81-ab74-83d8142f0d57')
.then((video) => {
  console.log(video);
})
curl 'https://civil-analytics.ideea.io/api/v1/extractions/9c56205e-c669-4e81-ab74-83d8142f0d57' \
  -X GET \
  -H 'Authorization: Bearer ACCESS_TOKEN'

Response

{
    "data": {
        "id": "9c56205e-c669-4e81-ab74-83d8142f0d57",
        "group_id": "2f8fdea3-b875-4926-90c8-5a1b11b818c8",
        "video_id": "9c56205e-c669-4e81-ab74-83d8142f0d57",
        "created_by": "aaaaaaaa-9a34-4466-ba4c-46438def7d7f",
        "model": "uk-sign",
        "status": "pending",
        "confidence_level": 0.1,
        "callback_url": "https://example.com/callback",
        "processing_time": 0,
        "charge_id": null,
        "output_video_url": null,
        "output_json_url": null,
        "updated_at": "2019-10-02T17:26:48.098Z",
        "created_at": "2019-10-02T17:26:48.098Z"
    },
    "meta": {},
    "status": "ok"
}

This endpoint will retrun a extraction by it's ID

HTTP Endpoint

GET https://civil-analytics.ideea.io/api/v1/extractions/{extraction_id}

Errors

The Ideea API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- The kitten requested is hidden for administrators only.
404 Not Found -- The specified kitten could not be found.
405 Method Not Allowed -- You tried to access a kitten with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
410 Gone -- The kitten requested has been removed from our servers.
418 I'm a teapot.
429 Too Many Requests -- You're requesting too many kittens! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.