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.

Broadsign offers the following storage options for the report:

  • Broadsign-Hosted Storage – No need to set up any storage on your end or provide credentials. The service will generate the report and return a pre-signed download URL directly in the response. The link stays valid for 24 hours.
  • AWS S3 Storage – The API response is a .csv file that can be stored on the supported AWS S3 storage service.
  • Azure Storage – The API response is a .csv file that can be stored on the supported Azure storage service.
  • Azure with SAS Token Storage – The API response is a .csv file that can be stored on the supported Azure storage service.

The Guaranteed Campaigns 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 Method: POST

Request URL: https://direct.broadsign.com/api/v1/reporting/screen_allocation

Documentation URL: Swagger /api/v1/reporting/screen_allocation

You can check the occupancy or availability information of digital screens or static faces. The request payload must have the storage credentials where you would like to store the API response.

You can use a Broadsign-hosted storage option by using the BROADSIGN type. The service will generate the report and return a pre-signed download URL directly in the response. The link stays valid for 24 hours.

Example Request

Copy 
curl --location 'https://direct.broadsign.net/api/v1/reporting/screen_allocation' \
--header 'Content-Type: application/json' \
--data '{
"storage": {
"type": "BROADSIGN"
}
}'

Example Response

Copy 
{
"transaction_id": "9f8b1c61-4d4a-4b7d-bcb4-2a8d8feec445",
"url": "https://broadsign-storage.s3.amazonaws.com/screens/allocation/Allocation_2025-01-12T15-22-09Z_9f8b1c61-4d4a-4b7d-bcb4-2a8d8feec445.csv.gz?X-Amz-Expires=86400&X-Amz-Signature=..."
}

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"    
        }
    }
}

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"
        }
    }
}

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 or face.
running_date Date when the screen or face 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 line 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 the Content and Network Management solution. For more information, see Share of Loop in the Content and Network Management documentation.