Skip to content

Forecast an audience

POST
/inventory/forecast
curl --request POST \
--url https://ads.wortise.com/api/public/v1/inventory/forecast \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '{ "audience": { "app": { "category": [ { "id": "example", "label": "example" } ], "list": [ { "icon": "example", "id": "example", "label": "example", "platform": "android" } ] }, "appFilters": { "coppa": true, "maxInstalls": 1, "minInstalls": 1, "minScore": 1, "platform": [ "android" ] }, "cpm": 1, "device": { "battery": { "plugged": true }, "brand": [ "example" ], "language": [ "example" ], "model": [ "example" ], "os": [ "android", "ios" ], "osVersion": [ "example" ], "type": [ "mobile" ] }, "location": [ { "countryCode": "example", "displayName": "example", "lat": 1, "lng": 1, "placeId": "example", "source": "google_places", "type": "place", "types": [ "example" ] } ], "user": { "gender": [ "female" ], "id": [ "example" ], "age": [ "-18" ], "interest": [ { "id": "example", "label": "example" } ] } }, "cost": 1, "not": { "app": { "category": [ { "id": "example", "label": "example" } ], "list": [ { "icon": "example", "id": "example", "label": "example", "platform": "android" } ] }, "appFilters": { "coppa": true, "maxInstalls": 1, "minInstalls": 1, "minScore": 1, "platform": [ "android" ] }, "cpm": 1, "device": { "battery": { "plugged": true }, "brand": [ "example" ], "language": [ "example" ], "model": [ "example" ], "os": [ "android", "ios" ], "osVersion": [ "example" ], "type": [ "mobile" ] }, "location": [ { "countryCode": "example", "displayName": "example", "lat": 1, "lng": 1, "placeId": "example", "source": "google_places", "type": "place", "types": [ "example" ] } ], "user": { "gender": [ "female" ], "id": [ "example" ], "age": [ "-18" ], "interest": [ { "id": "example", "label": "example" } ] } }, "size": [ "300x50" ], "slices": 25, "withApps": true }'

Counts the inventory an audience reaches and the impressions available at a CPM, with breakdowns.

Requires the inventory:read scope.

Media typeapplication/json
object
audience
object
app
object
category
Array<object>
object
id
required

E.g: “1”, “20”.

string
label
required
string
list
Array<object>
object
icon
string
id
required
string
label
required
string
platform
required
string
Allowed values: android ios web
appFilters
object
coppa
boolean
maxInstalls
number
minInstalls
number
minScore
number
<= 5
platform
Array<string>
Allowed values: android ios
cpm
number
> 0
device
object
battery
object
plugged
required
boolean
brand
Array<string>
language
Array<string>
model
Array<string>
os
Array<string>
default: android,ios
Allowed values: android ios
osVersion
Array<string>
type
Array<string>
Allowed values: mobile desktop tv tablet ??
location

Exact inventory locations or geographic areas to target.

Array
0
Any of:
One of:
object
countryCode
string
>= 2 characters <= 2 characters
displayName
required
string
lat
required
number
lng
required
number
placeId
required
string
source
required
string
Allowed value: google_places
type
required
string
Allowed value: place
types
required
Array<string>
user

Optional demographic filters. Age codes are ranges: -18=under 18, 18=18–24, 25=25–34, 35=35–44, 45=45–54, 55=55–64, 65=65+. Adults 18+ requires all six adult ranges, not just 18. Gender ?? means unknown, not all genders; omit gender on creation or use [] on update for unrestricted gender.

object
gender
Array<string>
Allowed values: female male ??
id
Array<string>
age
Array<string>
Allowed values: -18 18 25 35 45 55 65
interest
Array<object>
object
id
required
string
label
required
string
cost
number
not
object
app
object
category
Array<object>
object
id
required

E.g: “1”, “20”.

string
label
required
string
list
Array<object>
object
icon
string
id
required
string
label
required
string
platform
required
string
Allowed values: android ios web
appFilters
object
coppa
boolean
maxInstalls
number
minInstalls
number
minScore
number
<= 5
platform
Array<string>
Allowed values: android ios
cpm
number
> 0
device
object
battery
object
plugged
required
boolean
brand
Array<string>
language
Array<string>
model
Array<string>
os
Array<string>
default: android,ios
Allowed values: android ios
osVersion
Array<string>
type
Array<string>
Allowed values: mobile desktop tv tablet ??
location

Exact inventory locations or geographic areas to target.

Array
0
Any of:
One of:
object
countryCode
string
>= 2 characters <= 2 characters
displayName
required
string
lat
required
number
lng
required
number
placeId
required
string
source
required
string
Allowed value: google_places
type
required
string
Allowed value: place
types
required
Array<string>
user

Optional demographic filters. Age codes are ranges: -18=under 18, 18=18–24, 25=25–34, 35=35–44, 45=45–54, 55=55–64, 65=65+. Adults 18+ requires all six adult ranges, not just 18. Gender ?? means unknown, not all genders; omit gender on creation or use [] on update for unrestricted gender.

object
gender
Array<string>
Allowed values: female male ??
id
Array<string>
age
Array<string>
Allowed values: -18 18 25 35 45 55 65
interest
Array<object>
object
id
required
string
label
required
string
size
Array<string>
Allowed values: 300x50 300x250 320x50 interstitial native
slices
integer
default: 25 > 0 <= 9007199254740991
withApps
boolean

Inventory lookup result.

Media typeapplication/json
object
app
required
object
category
required
object
key
additional properties
object
clicks
integer
> 0 <= 9007199254740991
impressions
required
integer
> 0 <= 9007199254740991
id
required

Keyed by <platform>*<appId>, e.g. android*com.example; ?? is unknown

object
key
additional properties
object
clicks
integer
> 0 <= 9007199254740991
impressions
required
integer
> 0 <= 9007199254740991
categories
Array<string>
icon
string
name
string
platform
string
Allowed values: android ios web
score
number
cost
required

Cumulative impressions available up to each CPM price point of the sample

Array<object>
object
cpm
required
number
impressions
required
number
coverage
required

Share of total reached, 0-100

number
<= 100
cpm
required

Requested CPM in USD, or the recommended one when no cost is sent

number
device
required
object
type
required
object
key
additional properties
object
clicks
integer
> 0 <= 9007199254740991
impressions
required
integer
> 0 <= 9007199254740991
impression
required
object
total
required
number
unique
required
number
impressions
required

Impressions reachable at cpm

number
location
required
object
country
required

Keyed by ISO-2 country code; ?? is unknown

object
key
additional properties
object
clicks
integer
> 0 <= 9007199254740991
impressions
required
integer
> 0 <= 9007199254740991
size
required
object
key
additional properties
object
clicks
integer
> 0 <= 9007199254740991
impressions
required
integer
> 0 <= 9007199254740991
total
required

Impressions of the audience inventory

number
user
required
object
age
required
object
key
additional properties
object
clicks
integer
> 0 <= 9007199254740991
impressions
required
integer
> 0 <= 9007199254740991
gender
required
object
key
additional properties
object
clicks
integer
> 0 <= 9007199254740991
impressions
required
integer
> 0 <= 9007199254740991

Example

{
"app": {
"id": {
"additionalProperty": {
"platform": "android"
}
}
}
}

The JSON body is malformed or fails the input validation.

Media typeapplication/json
Any of:
object
errors
required

Zod issues

Array<object>
object
code
required
string
Allowed values: custom invalid_element invalid_format invalid_key invalid_type invalid_union invalid_value not_multiple_of too_big too_small unrecognized_keys
message
required
string
path
required

Location of the invalid field in the procedure input

Array
key
additional properties
message
required
string
Allowed value: Validation Error

Example

{
"errors": [
{
"code": "custom"
}
],
"message": "Validation Error"
}

The API key is missing, invalid, disabled or expired.

Media typeapplication/json
object
code
required

TRPC error code, e.g. UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT

string
Allowed values: PARSE_ERROR BAD_REQUEST INTERNAL_SERVER_ERROR NOT_IMPLEMENTED BAD_GATEWAY SERVICE_UNAVAILABLE GATEWAY_TIMEOUT UNAUTHORIZED PAYMENT_REQUIRED FORBIDDEN NOT_FOUND METHOD_NOT_SUPPORTED TIMEOUT CONFLICT PRECONDITION_FAILED PAYLOAD_TOO_LARGE UNSUPPORTED_MEDIA_TYPE UNPROCESSABLE_CONTENT PRECONDITION_REQUIRED TOO_MANY_REQUESTS CLIENT_CLOSED_REQUEST
message
required
string

Example

{
"code": "PARSE_ERROR"
}

The API key lacks the scope, or its owner lacks the dashboard permission.

Media typeapplication/json
object
code
required

TRPC error code, e.g. UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT

string
Allowed values: PARSE_ERROR BAD_REQUEST INTERNAL_SERVER_ERROR NOT_IMPLEMENTED BAD_GATEWAY SERVICE_UNAVAILABLE GATEWAY_TIMEOUT UNAUTHORIZED PAYMENT_REQUIRED FORBIDDEN NOT_FOUND METHOD_NOT_SUPPORTED TIMEOUT CONFLICT PRECONDITION_FAILED PAYLOAD_TOO_LARGE UNSUPPORTED_MEDIA_TYPE UNPROCESSABLE_CONTENT PRECONDITION_REQUIRED TOO_MANY_REQUESTS CLIENT_CLOSED_REQUEST
message
required
string

Example

{
"code": "PARSE_ERROR"
}

The API key exceeded its rate limit; retry after the Retry-After seconds.

Media typeapplication/json
object
code
required

TRPC error code, e.g. UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT

string
Allowed values: PARSE_ERROR BAD_REQUEST INTERNAL_SERVER_ERROR NOT_IMPLEMENTED BAD_GATEWAY SERVICE_UNAVAILABLE GATEWAY_TIMEOUT UNAUTHORIZED PAYMENT_REQUIRED FORBIDDEN NOT_FOUND METHOD_NOT_SUPPORTED TIMEOUT CONFLICT PRECONDITION_FAILED PAYLOAD_TOO_LARGE UNSUPPORTED_MEDIA_TYPE UNPROCESSABLE_CONTENT PRECONDITION_REQUIRED TOO_MANY_REQUESTS CLIENT_CLOSED_REQUEST
message
required
string

Example

{
"code": "PARSE_ERROR"
}
Retry-After
integer

Seconds to wait before retrying.

Unexpected server error.

Media typeapplication/json
object
code
required

TRPC error code, e.g. UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT

string
Allowed values: PARSE_ERROR BAD_REQUEST INTERNAL_SERVER_ERROR NOT_IMPLEMENTED BAD_GATEWAY SERVICE_UNAVAILABLE GATEWAY_TIMEOUT UNAUTHORIZED PAYMENT_REQUIRED FORBIDDEN NOT_FOUND METHOD_NOT_SUPPORTED TIMEOUT CONFLICT PRECONDITION_FAILED PAYLOAD_TOO_LARGE UNSUPPORTED_MEDIA_TYPE UNPROCESSABLE_CONTENT PRECONDITION_REQUIRED TOO_MANY_REQUESTS CLIENT_CLOSED_REQUEST
message
required
string

Example

{
"code": "PARSE_ERROR"
}