Lucit V1 Contract API

API Documentation Version : 1.13

​

The Lucit system provides a public API (Application Programming Interface) for out-of-home software systems to interface with our inventory-driven creatives.

This interface is targeted at Contract based campaigns where the OOH Operator has an existing or planned client, and Lucit powers the creative stream to your player software and we provide the statistics back to the client.

​

This API is superceded by the V3 api in most scenarios - See  https://www.lucit.cc/post/player-apps-choosing-between-lucit-v1-or-v3-api for help in choosing which one to use.

Process Overview

In its simplest form, the process works like this:

1. Your system makes a request to our API

2. We respond with an JSON Response or an XML Document containing a URI for a creative image (png or jpg)

3. Your system downloads the image, validates it, and displays it on the appropriate digital billboard

4. Your system provides proof of play by calling our analytics api with statistics

1. Requirements

• An API Token (This API requires a Public API Token that can be created by creating a new Lucit App, and generating a new Public token - See Creating your first application and see Creating Tokens

• An Export Id (Consider this a “Campaign Id”) (Please contact your Account Exec, or Contact Us)

• A list of digital asset locations that we store in our system (see required fields in Digital Display Asset Inventory Template Fields)

• An ability to consume a remote HTTPS JSON OR XML Response

  • Note, if you have specific digital displays that run on older software that does not support HTTPS, please contact us

​

2. Interface

Base URI

The base URI for the interface is:

https://pull.lucit.app/api/v1/{endPoint}/?api_token={your_api_token}

​

The API Interface for our contract interface provides a 4 endpoints. Either a json (default) endpoint or an XML endpoint

​

json: /campaigns/generic/{exportid}/pull

xml : /campaigns/generic/{exportid}/pull/xml

vast : /campaigns/generic/{exportid}/pull/vast  (experimental)

html : /campaigns/generic/{exportid}/pull/html (experimental)

​

An example full URI to retrieve an export (Campaign) might look something like this:

Sample Export Id : lch-MYID

Display ID : YOUR_DISPLAY_ID

Sample Api Token : SomeLong60CharString

Sample Complete URI: https://pull.lucit.app/api/v1/campaigns/generic/lch-MYID/pull?api_token=SomeLong60CharString&location_id=YOUR_DISPLAY_ID

​

This will return a single creative image for the digital board referenced in the location_id parameter

Optionally, for pre-caching purposes, you may retrieve the complete set of available creatives for each board by passing in the parameter show_all=1

Sample URI with location id: https://pull.lucit.app/api/v1/campaigns/generic/lch-MYID/pull?api_token=SomeLong60CharString&location_id=YOUR_DISPLAY_ID&show_all=1

3. Response

The response is in either JSON (default) or XML format and will return a minimum of 1 “set” and a single “item” in that set.

Each “pull” or “refresh” of the URI may or may not return a new “item.”

JSON response

​

{

"lucit_layout_drive": {

"source": "Layout by Lucit",

"source_href": "https://lucit.cc/lucit-layout",

"account": "Some Company Name",

"account_id": "lch-xxx",

"layout_export_id": "lch-xxx",

"layout_export_run_id": "1234",

"generated_datetime": "2020-01-05T18:04:05+00:00",

"layout_drive_schema_version": "1.0",

"item_sets": [

{

"location_id": "XXYYZZ.A",

"location_name": "123 N 45th St, W/S, your town",

"lucit_layout_digital_board_id": "12345",

"item_count": "7",

"item_total_weight": "70,

"item_selected_index": "5",

"items": [

{

"creative_id" : "C1-4C9D-LP-4PcU",

"creative_datetime": "2020-01-02T22:43:54+00:00",

"id": "1234"

"object_class" : "InventoryPhoto",

"name": "Name Of The Creative",

"slug": "name_of_the_creative",

"src": "https://the-image-server.com/the/path/to/the_creative_image.png",

"hash" : "d41d8cd98f00b204e9800998ecf8427e",

"hash_algo" : "md5",

"width": "840",

"height": "400"

"weight": "10",

"weight_pct": "0.14",

"pingback_url" : "https://track.lucit.app/api/v1/analytics/track/lucit-drive-play/?creative_id=C1-4C9D-LP-4PcU&lucit_layout_digital_board_id=12345&play_datetime=${PLAY_DATETIME_UTC}&play_duration=${PLAY_DURATION_SECONDS}&api_token=${API_TOKEN}

}

]

}

]

}

}

XML Response

<lucit-layout-drive 

source="Layout by Lucit" 

source-href="https://www.lucit.cc/lucit-layout" 

account="Some Company Name" 

account-id="lch-xxx" 

layout-export-id="lch-xxx" 

layout-export-run-id="1234" 

generated-datetime="2020-01-05T18:04:05+00:00" 

layout-drive-schema-version="1.0">

<item-set 

location-id="XXYYZZ.A" 

location-name="123 N 45th St, W/S, your town"

lucit-layout-digital-board-id="12345"

item-count="7" 

item-selected-index="5">

<item 

creative_id="C1-4C9D-LP-4PcU"

creative-datetime="2020-01-02T22:43:54+00:00" 

id="1234" 

"object-class"="InventoryPhoto"

name="Name Of The Creative" 

slug="name_of_the_creative" 

src="https://the-image-server.com/the/path/to/the_creative_image.png"  hash="d41d8cd98f00b204e9800998ecf8427e"

hash_algo="md5"

width="840" 

height="400" 

weight="10" 

weight-pct="0.14"

pingback-url="https://track.lucit.app/api/v1/analytics/track/lucit-drive-play/?creative_id=C1-4C9D-LP-4PcU&lucit_layout_digital_board_id=12345&play_datetime=${PLAY_DATETIME_UTC}&play_duration=${PLAY_DURATION_SECONDS}&api_token=${API_TOKEN}"

/>

</item-set>

</lucit-layout-drive>

​

4. Element Reference

​

JSON RESPONSE