Media

class Media(session_kwargs, client, return_type='raw')

Examples

>>> import civis
>>> client = civis.APIClient()
>>> client.media.list_spot_orders_shares(...)

Methods

delete_optimizations_runs(id, run_id)

Cancel a run

delete_optimizations_shares_groups(id, group_id)

Revoke the permissions a group has on this object

delete_optimizations_shares_users(id, user_id)

Revoke the permissions a user has on this object

delete_ratecards_shares_groups(id, group_id)

Revoke the permissions a group has on this object

delete_ratecards_shares_users(id, user_id)

Revoke the permissions a user has on this object

delete_spot_orders_shares_groups(id, group_id)

Revoke the permissions a group has on this object

delete_spot_orders_shares_users(id, user_id)

Revoke the permissions a user has on this object

get_optimizations(id)

Show a single optimization

get_optimizations_runs(id, run_id)

Check status of a run

get_ratecards(id)

Get a Ratecard

get_spot_orders(id)

Show a single spot order

list_dmas(*[, name, number])

List all Designated Market Areas

list_optimizations(*[, archived, limit, ...])

List all optimizations

list_optimizations_runs(id, *[, limit, ...])

List runs for the given Optimization job

list_optimizations_runs_logs(id, run_id, *)

Get the logs for a run

list_optimizations_shares(id)

List users and groups permissioned on this object

list_ratecards(*[, archived, filename, ...])

List all ratecards

list_ratecards_shares(id)

List users and groups permissioned on this object

list_spot_orders(*[, id, archived])

List all spot orders

list_spot_orders_shares(id)

List users and groups permissioned on this object

list_targets(*[, name, identifier, data_source])

List all Media Targets

patch_optimizations(id, *[, name, runs, ...])

Edit an existing optimization

patch_ratecards(id, *[, filename, start_on, ...])

Update some attributes of this Ratecard

post_optimizations(runs, *[, name, ...])

Create a new optimization

post_optimizations_clone(id)

Clone an existing optimization

post_optimizations_runs(id)

Start a run

post_ratecards(filename, start_on, end_on, ...)

Create a Ratecard

post_spot_orders(*[, body])

Create a spot order

put_optimizations_archive(id, status)

Update the archive status of this object

put_optimizations_shares_groups(id, ...[, ...])

Set the permissions groups has on this object

put_optimizations_shares_users(id, user_ids, ...)

Set the permissions users have on this object

put_ratecards(id, filename, start_on, ...)

Replace all attributes of this Ratecard

put_ratecards_archive(id, status)

Update the archive status of this object

put_ratecards_shares_groups(id, group_ids, ...)

Set the permissions groups has on this object

put_ratecards_shares_users(id, user_ids, ...)

Set the permissions users have on this object

put_spot_orders(id, *[, body])

Edit the specified spot order

put_spot_orders_archive(id, status)

Update the archive status of this object

put_spot_orders_shares_groups(id, group_ids, ...)

Set the permissions groups has on this object

put_spot_orders_shares_users(id, user_ids, ...)

Set the permissions users have on this object
delete_optimizations_runs(id: int, run_id: int)

Cancel a run

Parameters:
idint

The ID of the Optimization job.

run_idint

The ID of the run.

Returns:
None

Response code 202: success

delete_optimizations_shares_groups(id: int, group_id: int)

Revoke the permissions a group has on this object

Parameters:
idint

The ID of the resource that is shared.

group_idint

The ID of the group.

Returns:
None

Response code 204: success

delete_optimizations_shares_users(id: int, user_id: int)

Revoke the permissions a user has on this object

Parameters:
idint

The ID of the resource that is shared.

user_idint

The ID of the user.

Returns:
None

Response code 204: success

delete_ratecards_shares_groups(id: int, group_id: int)

Revoke the permissions a group has on this object

Parameters:
idint

The ID of the resource that is shared.

group_idint

The ID of the group.

Returns:
None

Response code 204: success

delete_ratecards_shares_users(id: int, user_id: int)

Revoke the permissions a user has on this object

Parameters:
idint

The ID of the resource that is shared.

user_idint

The ID of the user.

Returns:
None

Response code 204: success

delete_spot_orders_shares_groups(id: int, group_id: int)

Revoke the permissions a group has on this object

Parameters:
idint

The ID of the resource that is shared.

group_idint

The ID of the group.

Returns:
None

Response code 204: success

delete_spot_orders_shares_users(id: int, user_id: int)

Revoke the permissions a user has on this object

Parameters:
idint

The ID of the resource that is shared.

user_idint

The ID of the user.

Returns:
None

Response code 204: success

get_optimizations(id: int)

Show a single optimization

Parameters:
idint

The optimization ID.

Returns:
civis.response.Response
  • idint

    The optimization ID.

  • authordict
    • idint

      The ID of this user.

    • namestr

      This user’s name.

    • usernamestr

      This user’s username.

    • initialsstr

      This user’s initials.

    • onlinebool

      Whether this user is online.

  • namestr

    The name of the optimization.

  • created_at : str (time)

  • updated_at : str (time)

  • finished_atstr (date-time)

    The end time of the last run.

  • statestr

    The state of the last run.

  • last_run_idint

    The ID of the last run.

  • spot_order_idint

    The ID for the spot order produced by the optimization.

  • archivedstr

    The archival status of the requested item(s).

  • report_linkstr

    A link to the visual report for the optimization.

  • spot_order_linkstr

    A link to the json version of the spot order.

  • file_linksList[str]

    Links to the csv and xml versions of the spot order.

  • runsList[dict]

    The runs of the optimization.

    • market_idint

      The market ID.

    • start_datestr (date)

      The start date for the media run.

    • end_datestr (date)

      The end date for the media run.

    • force_cpmbool

      Whether to force optimization to use CPM data even if partition data is available.

    • reach_alphafloat (float)

      A tuning parameter used to adjust RF.

    • syscodesList[int]

      The syscodes for the media run.

    • rate_cardsList[str]

      The ratecards for the media run.

    • constraintsList[dict]

      The constraints for the media run.

      • targetsList[str]

        The targets to constrain.

      • budgetfloat (float)

        The maximum budget for these targets.

      • frequencyfloat (float)

        The maximum frequency for these targets.

  • programsList[str]

    An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

  • networksList[str]

    An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

  • exclude_programsbool

    If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

  • exclude_networksbool

    If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

  • time_slot_percentagesdict

    The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

get_optimizations_runs(id: int, run_id: int)

Check status of a run

Parameters:
idint

The ID of the Optimization job.

run_idint

The ID of the run.

Returns:
civis.response.Response
  • idint

    The ID of the run.

  • optimization_idint

    The ID of the Optimization job.

  • statestr

    The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

  • is_cancel_requestedbool

    True if run cancel requested, else false.

  • created_atstr (time)

    The time the run was created.

  • started_atstr (time)

    The time the run started at.

  • finished_atstr (time)

    The time the run completed.

  • errorstr

    The error, if any, returned by the run.

get_ratecards(id: int)

Get a Ratecard

Parameters:
idint
Returns:
civis.response.Response
  • idint

    The ratecard ID.

  • filenamestr

    Name of the ratecard file.

  • start_onstr (date)

    First day to which the ratecard applies.

  • end_onstr (date)

    Last day to which the ratecard applies.

  • dma_numberint

    Number of the DMA associated with the ratecard.

  • archivedstr

    The archival status of the requested item(s).

get_spot_orders(id: int)

Show a single spot order

Parameters:
idint

The ID for the spot order.

Returns:
civis.response.Response
  • idint

    The ID for the spot order.

  • archivedstr

    The archival status of the requested item(s).

  • csv_s3_uristr

    S3 URI for the spot order CSV file.

  • json_s3_uristr

    S3 URI for the spot order JSON file.

  • xml_archive_s3_uristr

    S3 URI for the spot order XML archive.

  • last_transform_job_idint

    ID of the spot order transformation job.

list_dmas(*, name: str = None, number: int = None)

List all Designated Market Areas

Parameters:
namestr, optional

If specified, will be used to filter the DMAs returned. Substring matching is supported with “%” and “*” wildcards (e.g., “name=%region%” will return both “region1” and “my region”).

numberint, optional

If specified, will be used to filter the DMAS by number.

Returns:
civis.response.Response
  • namestr

    Name for the DMA region.

  • numberint

    Identifier number for a DMA.

list_optimizations(*, archived: str = None, limit: int = None, page_num: int = None, order: str = None, order_dir: str = None, iterator: bool = None)

List all optimizations

Parameters:
archivedstr, optional

The archival status of the requested item(s).

limitint, optional

Number of results to return. Defaults to 20. Maximum allowed is 50.

page_numint, optional

Page number of the results to return. Defaults to the first page, 1.

orderstr, optional

The field on which to order the result set. Defaults to created_at. Must be one of: created_at, author, name.

order_dirstr, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iteratorbool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:
civis.response.PaginatedResponse
  • idint

    The optimization ID.

  • authordict
    • idint

      The ID of this user.

    • namestr

      This user’s name.

    • usernamestr

      This user’s username.

    • initialsstr

      This user’s initials.

    • onlinebool

      Whether this user is online.

  • namestr

    The name of the optimization.

  • created_at : str (time)

  • updated_at : str (time)

  • finished_atstr (date-time)

    The end time of the last run.

  • statestr

    The state of the last run.

  • last_run_idint

    The ID of the last run.

  • spot_order_idint

    The ID for the spot order produced by the optimization.

  • archivedstr

    The archival status of the requested item(s).

list_optimizations_runs(id: int, *, limit: int = None, page_num: int = None, order: str = None, order_dir: str = None, iterator: bool = None)

List runs for the given Optimization job

Parameters:
idint

The ID of the Optimization job.

limitint, optional

Number of results to return. Defaults to 20. Maximum allowed is 100.

page_numint, optional

Page number of the results to return. Defaults to the first page, 1.

orderstr, optional

The field on which to order the result set. Defaults to id. Must be one of: id.

order_dirstr, optional

Direction in which to sort, either asc (ascending) or desc (descending) defaulting to desc.

iteratorbool, optional

If True, return a generator to iterate over all responses. Use when more results than the maximum allowed by limit are needed. When True, limit and page_num are ignored. Defaults to False.

Returns:
civis.response.PaginatedResponse
  • idint

    The ID of the run.

  • optimization_idint

    The ID of the Optimization job.

  • statestr

    The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

  • is_cancel_requestedbool

    True if run cancel requested, else false.

  • created_atstr (time)

    The time the run was created.

  • started_atstr (time)

    The time the run started at.

  • finished_atstr (time)

    The time the run completed.

  • errorstr

    The error, if any, returned by the run.

list_optimizations_runs_logs(id: int, run_id: int, *, last_id: int = None, limit: int = None)

Get the logs for a run

Parameters:
idint

The ID of the Optimization job.

run_idint

The ID of the run.

last_idint, optional

The ID of the last log message received. Log entries with this ID value or lower will be omitted.Logs are sorted by ID if this value is provided, and are otherwise sorted by createdAt.

limitint, optional

The maximum number of log messages to return. Default of 10000.

Returns:
civis.response.Response
  • idint

    The ID of the log.

  • created_atstr (date-time)

    The time the log was created.

  • messagestr

    The log message.

  • levelstr

    The level of the log. One of unknown,fatal,error,warn,info,debug.

list_optimizations_shares(id: int)

List users and groups permissioned on this object

Parameters:
idint

The ID of the resource that is shared.

Returns:
civis.response.Response
  • readersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • writersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • ownersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • total_user_sharesint

    For owners, the number of total users shared. For writers and readers, the number of visible users shared.

  • total_group_sharesint

    For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

list_ratecards(*, archived: str = None, filename: str = None, dma_number: int = None)

List all ratecards

Parameters:
archivedstr, optional

The archival status of the requested item(s).

filenamestr, optional

If specified, will be used to filter the ratecards returned. Substring matching is supported with “%” and “*” wildcards (e.g., “filename=%ratecard%” will return both “ratecard 1” and “my ratecard”).

dma_numberint, optional

If specified, will be used to filter the ratecards by DMA.

Returns:
civis.response.Response
  • idint

    The ratecard ID.

  • filenamestr

    Name of the ratecard file.

  • start_onstr (date)

    First day to which the ratecard applies.

  • end_onstr (date)

    Last day to which the ratecard applies.

  • dma_numberint

    Number of the DMA associated with the ratecard.

  • archivedstr

    The archival status of the requested item(s).

list_ratecards_shares(id: int)

List users and groups permissioned on this object

Parameters:
idint

The ID of the resource that is shared.

Returns:
civis.response.Response
  • readersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • writersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • ownersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • total_user_sharesint

    For owners, the number of total users shared. For writers and readers, the number of visible users shared.

  • total_group_sharesint

    For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

list_spot_orders(*, id: int = None, archived: str = None)

List all spot orders

Parameters:
idint, optional

The ID for the spot order.

archivedstr, optional

The archival status of the requested item(s).

Returns:
civis.response.Response
  • idint

    The ID for the spot order.

  • archivedstr

    The archival status of the requested item(s).

list_spot_orders_shares(id: int)

List users and groups permissioned on this object

Parameters:
idint

The ID of the resource that is shared.

Returns:
civis.response.Response
  • readersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • writersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • ownersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • total_user_sharesint

    For owners, the number of total users shared. For writers and readers, the number of visible users shared.

  • total_group_sharesint

    For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

list_targets(*, name: str = None, identifier: str = None, data_source: str = None)

List all Media Targets

Parameters:
namestr, optional

The name of the target.

identifierstr, optional

A unique identifier for this target.

data_sourcestr, optional

The source of viewership data for this target.

Returns:
civis.response.Response
  • namestr

    The name of the target.

  • identifierstr

    A unique identifier for this target.

  • data_sourcestr

    The source of viewership data for this target.

patch_optimizations(id: int, *, name: str = None, runs: List[dict] = None, programs: List[str] = None, networks: List[str] = None, exclude_programs: bool = None, exclude_networks: bool = None, time_slot_percentages: dict = None)

Edit an existing optimization

Parameters:
idint

The optimization ID.

namestr, optional

The name of the optimization.

runsList[dict], optional

The runs of the optimization.

  • market_idint

    The market ID.

  • start_datestr (date)

    The start date for the media run.

  • end_datestr (date)

    The end date for the media run.

  • force_cpmbool

    Whether to force optimization to use CPM data even if partition data is available.

  • reach_alphafloat (float)

    A tuning parameter used to adjust RF.

  • syscodesList[int]

    The syscodes for the media run.

  • rate_cardsList[str]

    The ratecards for the media run.

  • constraintsList[dict]

    The constraints for the media run.

    • targetsList[str]

      The targets to constrain.

    • budgetfloat (float)

      The maximum budget for these targets.

    • frequencyfloat (float)

      The maximum frequency for these targets.

programsList[str], optional

An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

networksList[str], optional

An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

exclude_programsbool, optional

If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

exclude_networksbool, optional

If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

time_slot_percentagesdict, optional

The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

Returns:
civis.response.Response
  • idint

    The optimization ID.

  • authordict
    • idint

      The ID of this user.

    • namestr

      This user’s name.

    • usernamestr

      This user’s username.

    • initialsstr

      This user’s initials.

    • onlinebool

      Whether this user is online.

  • namestr

    The name of the optimization.

  • created_at : str (time)

  • updated_at : str (time)

  • finished_atstr (date-time)

    The end time of the last run.

  • statestr

    The state of the last run.

  • last_run_idint

    The ID of the last run.

  • spot_order_idint

    The ID for the spot order produced by the optimization.

  • archivedstr

    The archival status of the requested item(s).

  • report_linkstr

    A link to the visual report for the optimization.

  • spot_order_linkstr

    A link to the json version of the spot order.

  • file_linksList[str]

    Links to the csv and xml versions of the spot order.

  • runsList[dict]

    The runs of the optimization.

    • market_idint

      The market ID.

    • start_datestr (date)

      The start date for the media run.

    • end_datestr (date)

      The end date for the media run.

    • force_cpmbool

      Whether to force optimization to use CPM data even if partition data is available.

    • reach_alphafloat (float)

      A tuning parameter used to adjust RF.

    • syscodesList[int]

      The syscodes for the media run.

    • rate_cardsList[str]

      The ratecards for the media run.

    • constraintsList[dict]

      The constraints for the media run.

      • targetsList[str]

        The targets to constrain.

      • budgetfloat (float)

        The maximum budget for these targets.

      • frequencyfloat (float)

        The maximum frequency for these targets.

  • programsList[str]

    An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

  • networksList[str]

    An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

  • exclude_programsbool

    If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

  • exclude_networksbool

    If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

  • time_slot_percentagesdict

    The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

patch_ratecards(id: int, *, filename: str = None, start_on: str = None, end_on: str = None, dma_number: int = None)

Update some attributes of this Ratecard

Parameters:
idint

The ratecard ID.

filenamestr, optional

Name of the ratecard file.

start_onstr (date), optional

First day to which the ratecard applies.

end_onstr (date), optional

Last day to which the ratecard applies.

dma_numberint, optional

Number of the DMA associated with the ratecard.

Returns:
civis.response.Response
  • idint

    The ratecard ID.

  • filenamestr

    Name of the ratecard file.

  • start_onstr (date)

    First day to which the ratecard applies.

  • end_onstr (date)

    Last day to which the ratecard applies.

  • dma_numberint

    Number of the DMA associated with the ratecard.

  • archivedstr

    The archival status of the requested item(s).

post_optimizations(runs: List[dict], *, name: str = None, programs: List[str] = None, networks: List[str] = None, exclude_programs: bool = None, exclude_networks: bool = None, time_slot_percentages: dict = None)

Create a new optimization

Parameters:
runsList[dict]

The runs of the optimization.

  • market_idint

    The market ID.

  • start_datestr (date)

    The start date for the media run.

  • end_datestr (date)

    The end date for the media run.

  • force_cpmbool

    Whether to force optimization to use CPM data even if partition data is available.

  • reach_alphafloat (float)

    A tuning parameter used to adjust RF.

  • syscodesList[int]

    The syscodes for the media run.

  • rate_cardsList[str]

    The ratecards for the media run.

  • constraintsList[dict]

    The constraints for the media run.

    • targetsList[str]

      The targets to constrain.

    • budgetfloat (float)

      The maximum budget for these targets.

    • frequencyfloat (float)

      The maximum frequency for these targets.

namestr, optional

The name of the optimization.

programsList[str], optional

An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

networksList[str], optional

An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

exclude_programsbool, optional

If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

exclude_networksbool, optional

If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

time_slot_percentagesdict, optional

The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

Returns:
civis.response.Response
  • idint

    The optimization ID.

  • authordict
    • idint

      The ID of this user.

    • namestr

      This user’s name.

    • usernamestr

      This user’s username.

    • initialsstr

      This user’s initials.

    • onlinebool

      Whether this user is online.

  • namestr

    The name of the optimization.

  • created_at : str (time)

  • updated_at : str (time)

  • finished_atstr (date-time)

    The end time of the last run.

  • statestr

    The state of the last run.

  • last_run_idint

    The ID of the last run.

  • spot_order_idint

    The ID for the spot order produced by the optimization.

  • archivedstr

    The archival status of the requested item(s).

  • report_linkstr

    A link to the visual report for the optimization.

  • spot_order_linkstr

    A link to the json version of the spot order.

  • file_linksList[str]

    Links to the csv and xml versions of the spot order.

  • runsList[dict]

    The runs of the optimization.

    • market_idint

      The market ID.

    • start_datestr (date)

      The start date for the media run.

    • end_datestr (date)

      The end date for the media run.

    • force_cpmbool

      Whether to force optimization to use CPM data even if partition data is available.

    • reach_alphafloat (float)

      A tuning parameter used to adjust RF.

    • syscodesList[int]

      The syscodes for the media run.

    • rate_cardsList[str]

      The ratecards for the media run.

    • constraintsList[dict]

      The constraints for the media run.

      • targetsList[str]

        The targets to constrain.

      • budgetfloat (float)

        The maximum budget for these targets.

      • frequencyfloat (float)

        The maximum frequency for these targets.

  • programsList[str]

    An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

  • networksList[str]

    An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

  • exclude_programsbool

    If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

  • exclude_networksbool

    If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

  • time_slot_percentagesdict

    The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

post_optimizations_clone(id: int)

Clone an existing optimization

Parameters:
idint

The optimization ID.

Returns:
civis.response.Response
  • idint

    The optimization ID.

  • authordict
    • idint

      The ID of this user.

    • namestr

      This user’s name.

    • usernamestr

      This user’s username.

    • initialsstr

      This user’s initials.

    • onlinebool

      Whether this user is online.

  • namestr

    The name of the optimization.

  • created_at : str (time)

  • updated_at : str (time)

  • finished_atstr (date-time)

    The end time of the last run.

  • statestr

    The state of the last run.

  • last_run_idint

    The ID of the last run.

  • spot_order_idint

    The ID for the spot order produced by the optimization.

  • archivedstr

    The archival status of the requested item(s).

  • report_linkstr

    A link to the visual report for the optimization.

  • spot_order_linkstr

    A link to the json version of the spot order.

  • file_linksList[str]

    Links to the csv and xml versions of the spot order.

  • runsList[dict]

    The runs of the optimization.

    • market_idint

      The market ID.

    • start_datestr (date)

      The start date for the media run.

    • end_datestr (date)

      The end date for the media run.

    • force_cpmbool

      Whether to force optimization to use CPM data even if partition data is available.

    • reach_alphafloat (float)

      A tuning parameter used to adjust RF.

    • syscodesList[int]

      The syscodes for the media run.

    • rate_cardsList[str]

      The ratecards for the media run.

    • constraintsList[dict]

      The constraints for the media run.

      • targetsList[str]

        The targets to constrain.

      • budgetfloat (float)

        The maximum budget for these targets.

      • frequencyfloat (float)

        The maximum frequency for these targets.

  • programsList[str]

    An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

  • networksList[str]

    An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

  • exclude_programsbool

    If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

  • exclude_networksbool

    If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

  • time_slot_percentagesdict

    The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

post_optimizations_runs(id: int)

Start a run

Parameters:
idint

The ID of the Optimization job.

Returns:
civis.response.Response
  • idint

    The ID of the run.

  • optimization_idint

    The ID of the Optimization job.

  • statestr

    The state of the run, one of ‘queued’ ‘running’ ‘succeeded’ ‘failed’ or ‘cancelled’.

  • is_cancel_requestedbool

    True if run cancel requested, else false.

  • created_atstr (time)

    The time the run was created.

  • started_atstr (time)

    The time the run started at.

  • finished_atstr (time)

    The time the run completed.

  • errorstr

    The error, if any, returned by the run.

post_ratecards(filename: str, start_on: str, end_on: str, dma_number: int)

Create a Ratecard

Parameters:
filenamestr

Name of the ratecard file.

start_onstr (date)

First day to which the ratecard applies.

end_onstr (date)

Last day to which the ratecard applies.

dma_numberint

Number of the DMA associated with the ratecard.

Returns:
civis.response.Response
  • idint

    The ratecard ID.

  • filenamestr

    Name of the ratecard file.

  • start_onstr (date)

    First day to which the ratecard applies.

  • end_onstr (date)

    Last day to which the ratecard applies.

  • dma_numberint

    Number of the DMA associated with the ratecard.

  • archivedstr

    The archival status of the requested item(s).

post_spot_orders(*, body: str = None)

Create a spot order

Parameters:
bodystr, optional

CSV body of a spot order.

Returns:
civis.response.Response
  • idint

    The ID for the spot order.

  • archivedstr

    The archival status of the requested item(s).

  • csv_s3_uristr

    S3 URI for the spot order CSV file.

  • json_s3_uristr

    S3 URI for the spot order JSON file.

  • xml_archive_s3_uristr

    S3 URI for the spot order XML archive.

  • last_transform_job_idint

    ID of the spot order transformation job.

put_optimizations_archive(id: int, status: bool)

Update the archive status of this object

Parameters:
idint

The ID of the object.

statusbool

The desired archived status of the object.

Returns:
civis.response.Response
  • idint

    The optimization ID.

  • authordict
    • idint

      The ID of this user.

    • namestr

      This user’s name.

    • usernamestr

      This user’s username.

    • initialsstr

      This user’s initials.

    • onlinebool

      Whether this user is online.

  • namestr

    The name of the optimization.

  • created_at : str (time)

  • updated_at : str (time)

  • finished_atstr (date-time)

    The end time of the last run.

  • statestr

    The state of the last run.

  • last_run_idint

    The ID of the last run.

  • spot_order_idint

    The ID for the spot order produced by the optimization.

  • archivedstr

    The archival status of the requested item(s).

  • report_linkstr

    A link to the visual report for the optimization.

  • spot_order_linkstr

    A link to the json version of the spot order.

  • file_linksList[str]

    Links to the csv and xml versions of the spot order.

  • runsList[dict]

    The runs of the optimization.

    • market_idint

      The market ID.

    • start_datestr (date)

      The start date for the media run.

    • end_datestr (date)

      The end date for the media run.

    • force_cpmbool

      Whether to force optimization to use CPM data even if partition data is available.

    • reach_alphafloat (float)

      A tuning parameter used to adjust RF.

    • syscodesList[int]

      The syscodes for the media run.

    • rate_cardsList[str]

      The ratecards for the media run.

    • constraintsList[dict]

      The constraints for the media run.

      • targetsList[str]

        The targets to constrain.

      • budgetfloat (float)

        The maximum budget for these targets.

      • frequencyfloat (float)

        The maximum frequency for these targets.

  • programsList[str]

    An array of programs that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_programs is not also set.

  • networksList[str]

    An array of networks that the Civis Media Optimizer either exclude or limit to.An error will be thrown if exclude_networks is not also set.

  • exclude_programsbool

    If Civis Media Optimizer should exclude the programs in the programs parameter.If this value is set to false, it will make the optimization limit itself to the programs supplied through the programs parameter.An error will be thrown if programs is not also set.

  • exclude_networksbool

    If Civis Media Optimizer should exclude the networks in the networks parameter.If this value is set to false, it will make the optimization limit itself to the networks supplied through the networks.An error will be thrown if networks is not also set.

  • time_slot_percentagesdict

    The maximum amount of the budget spent on that particular day of the week, daypart, or specific time slot for broadcast and cable.

put_optimizations_shares_groups(id: int, group_ids: List[int], permission_level: str, *, share_email_body: str = None, send_shared_email: bool = None)

Set the permissions groups has on this object

Parameters:
idint

The ID of the resource that is shared.

group_idsList[int]

An array of one or more group IDs.

permission_levelstr

Options are: “read”, “write”, or “manage”.

share_email_bodystr, optional

Custom body text for e-mail sent on a share.

send_shared_emailbool, optional

Send email to the recipients of a share.

Returns:
civis.response.Response
  • readersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • writersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • ownersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • total_user_sharesint

    For owners, the number of total users shared. For writers and readers, the number of visible users shared.

  • total_group_sharesint

    For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_optimizations_shares_users(id: int, user_ids: List[int], permission_level: str, *, share_email_body: str = None, send_shared_email: bool = None)

Set the permissions users have on this object

Parameters:
idint

The ID of the resource that is shared.

user_idsList[int]

An array of one or more user IDs.

permission_levelstr

Options are: “read”, “write”, or “manage”.

share_email_bodystr, optional

Custom body text for e-mail sent on a share.

send_shared_emailbool, optional

Send email to the recipients of a share.

Returns:
civis.response.Response
  • readersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • writersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • ownersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • total_user_sharesint

    For owners, the number of total users shared. For writers and readers, the number of visible users shared.

  • total_group_sharesint

    For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_ratecards(id: int, filename: str, start_on: str, end_on: str, dma_number: int)

Replace all attributes of this Ratecard

Parameters:
idint

The ratecard ID.

filenamestr

Name of the ratecard file.

start_onstr (date)

First day to which the ratecard applies.

end_onstr (date)

Last day to which the ratecard applies.

dma_numberint

Number of the DMA associated with the ratecard.

Returns:
civis.response.Response
  • idint

    The ratecard ID.

  • filenamestr

    Name of the ratecard file.

  • start_onstr (date)

    First day to which the ratecard applies.

  • end_onstr (date)

    Last day to which the ratecard applies.

  • dma_numberint

    Number of the DMA associated with the ratecard.

  • archivedstr

    The archival status of the requested item(s).

put_ratecards_archive(id: int, status: bool)

Update the archive status of this object

Parameters:
idint

The ID of the object.

statusbool

The desired archived status of the object.

Returns:
civis.response.Response
  • idint

    The ratecard ID.

  • filenamestr

    Name of the ratecard file.

  • start_onstr (date)

    First day to which the ratecard applies.

  • end_onstr (date)

    Last day to which the ratecard applies.

  • dma_numberint

    Number of the DMA associated with the ratecard.

  • archivedstr

    The archival status of the requested item(s).

put_ratecards_shares_groups(id: int, group_ids: List[int], permission_level: str, *, share_email_body: str = None, send_shared_email: bool = None)

Set the permissions groups has on this object

Parameters:
idint

The ID of the resource that is shared.

group_idsList[int]

An array of one or more group IDs.

permission_levelstr

Options are: “read”, “write”, or “manage”.

share_email_bodystr, optional

Custom body text for e-mail sent on a share.

send_shared_emailbool, optional

Send email to the recipients of a share.

Returns:
civis.response.Response
  • readersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • writersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • ownersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • total_user_sharesint

    For owners, the number of total users shared. For writers and readers, the number of visible users shared.

  • total_group_sharesint

    For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_ratecards_shares_users(id: int, user_ids: List[int], permission_level: str, *, share_email_body: str = None, send_shared_email: bool = None)

Set the permissions users have on this object

Parameters:
idint

The ID of the resource that is shared.

user_idsList[int]

An array of one or more user IDs.

permission_levelstr

Options are: “read”, “write”, or “manage”.

share_email_bodystr, optional

Custom body text for e-mail sent on a share.

send_shared_emailbool, optional

Send email to the recipients of a share.

Returns:
civis.response.Response
  • readersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • writersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • ownersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • total_user_sharesint

    For owners, the number of total users shared. For writers and readers, the number of visible users shared.

  • total_group_sharesint

    For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_spot_orders(id: int, *, body: str = None)

Edit the specified spot order

Parameters:
idint

The ID for the spot order.

bodystr, optional

CSV body of a spot order.

Returns:
civis.response.Response
  • idint

    The ID for the spot order.

  • archivedstr

    The archival status of the requested item(s).

  • csv_s3_uristr

    S3 URI for the spot order CSV file.

  • json_s3_uristr

    S3 URI for the spot order JSON file.

  • xml_archive_s3_uristr

    S3 URI for the spot order XML archive.

  • last_transform_job_idint

    ID of the spot order transformation job.

put_spot_orders_archive(id: int, status: bool)

Update the archive status of this object

Parameters:
idint

The ID of the object.

statusbool

The desired archived status of the object.

Returns:
civis.response.Response
  • idint

    The ID for the spot order.

  • archivedstr

    The archival status of the requested item(s).

  • csv_s3_uristr

    S3 URI for the spot order CSV file.

  • json_s3_uristr

    S3 URI for the spot order JSON file.

  • xml_archive_s3_uristr

    S3 URI for the spot order XML archive.

  • last_transform_job_idint

    ID of the spot order transformation job.

put_spot_orders_shares_groups(id: int, group_ids: List[int], permission_level: str, *, share_email_body: str = None, send_shared_email: bool = None)

Set the permissions groups has on this object

Parameters:
idint

The ID of the resource that is shared.

group_idsList[int]

An array of one or more group IDs.

permission_levelstr

Options are: “read”, “write”, or “manage”.

share_email_bodystr, optional

Custom body text for e-mail sent on a share.

send_shared_emailbool, optional

Send email to the recipients of a share.

Returns:
civis.response.Response
  • readersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • writersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • ownersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • total_user_sharesint

    For owners, the number of total users shared. For writers and readers, the number of visible users shared.

  • total_group_sharesint

    For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.

put_spot_orders_shares_users(id: int, user_ids: List[int], permission_level: str, *, share_email_body: str = None, send_shared_email: bool = None)

Set the permissions users have on this object

Parameters:
idint

The ID of the resource that is shared.

user_idsList[int]

An array of one or more user IDs.

permission_levelstr

Options are: “read”, “write”, or “manage”.

share_email_bodystr, optional

Custom body text for e-mail sent on a share.

send_shared_emailbool, optional

Send email to the recipients of a share.

Returns:
civis.response.Response
  • readersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • writersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • ownersdict
    • usersList[dict]

      • id : int

      • name : str

    • groupsList[dict]

      • id : int

      • name : str

  • total_user_sharesint

    For owners, the number of total users shared. For writers and readers, the number of visible users shared.

  • total_group_sharesint

    For owners, the number of total groups shared. For writers and readers, the number of visible groups shared.