Use the Screen Allocation API

This example illustrates how to get occupancy or availability information of the inventory from one month in the past up to 18 months in the future.

The API response is a .csv file that can be stored on the supported AWS and Azure storage services.

The Broadsign Direct REST API endpoints and parameters are described in the REST Method Reference.

Note: The ID#s we use in these samples are for illustration purposes. They are invalid. Be sure to use your own ID#s for your integrations.

Note: All request body examples in this document are raw JSONs.

Request Samples

The request payload differs depending on the storage service used.

Request (S3)

Copy

{
    "storage":{
        "type":"s3",
        "credentials": {        
            "cloud_access_id":"id",    
            "cloud_access_key": "key",    
            "bucket_name":"demo-bucket-testing"
            “folder_name”: "XYZ"
        }
    }
}

Request (Azure)

Copy

{
    "storage":{
        "type":"AZURE",
        "credentials": {
            "Connection_string": "DefaultEndpointsProtocol=https;AccountName=demotestbroadsign;AccountKey=KEY;EndpointSuffix=core.windows.net",
             "container_name":"testdemocci"
        }
    }
}

Request (Azure with SAS Token)

Note: The following minimum permissions are required in the SAS token to run the endpoint: Write and Delete.

Copy

{
    "storage": {
        "type": "AZURE",
        "credentials": {
            "account_endpoint": "https://zdlsneurdcpstg.blob.core.windows.net",
            "container_name": "datalake",
            "file_directory": "raw/broadsign/bsd/allocations/2023/04/04/Norway",
            "shared_access_signature_token": "se=2023-04-06T13%3A27%3A48Z&sp=racwd&sv=2021-12-02&sr=d&sdd=8&sig=CleT81TTD/22EpkTznoqh4HG%2BZoUY3KWk9Kk7Zoab6A%3D"
        }
    }
}

Response

The response file format is a compressed .csv file stored in the preferred storage service specified by the user.

The following is a sample response file:

The following are the details of the fields in the response file:

Field Name	Description
screen_id	Unique identification unit for a screen.
running_date	Date when the screen is active.
running_times	Opening hours of the screen.
dow_mask	Days of the week on which the screen is active. Example: Mon - 1, Tue - 2, Wed - 4, Thu - 8, Fri - 16, Sat - 32, Sun - 64
audience_calculation _method	Audience calculation method of the screen (Prorated or Dwell).
sum_slot_duration	Sum of all booked or held slots within the loop (in seconds). Example: if `proposal_item_pressure` = {line id1 - 2, line id2 - 4} – the `sum_slot_duration` of the screen for that duration will be 6 seconds.
sum_slot_duration_held	Sum of all held slots within the loop (in seconds). The time (in seconds) of all the held line items within the loop will contribute to this number.
sum_slot_duration_takeover	Sum of all booked or held slots by Takeovers within the loop (in seconds).
impressions	Impression count per hour.
cpm	Cost per 1000 impressions derived from the Rate Cards.
proposal_item_pressure	Array of information about space occupied by each proposal item on the screen (time booked and held in seconds per loop).
fixed_slot_duration	Duration within a loop that is fixed for editorial content and not available for booking.
loop_duration	Total duration of the loop or the loop length.
real_loop_duration	Duration within a loop that is available for booking. This is set in Broadsign Control. For more information, see Share of Loop in the Broadsign Control documentation.