The Shape API is a graphQL based platform. From a high level, the API is composed of:
These are the individual entities that can be accessed. This includes advertising entities such as campaigns, ads, and keywords.
Associations are the entities which an object contains or has access to. For example, an account’s associations include campaigns, adgroups, ads, etc. A campaign’s associations include adgroups, ads, keywords, etc.
Fields are the attributes of a given object. A campaign has fields such as clicks, conversions, status, etc.
Segmentations provide an alternate look at the metrics of certain objects. They divide metric totals into groups such as network type, day of the year, or device type.
All requests to the Shape API must, at a minimum, specify an object type (otype) and a code. For example, a request to pull data for a campaign would have the following form:
{
status: "success",
message: "",
errors: null,
data: {
campaigns: {
code_campaign: "14140888783"
}
}
}
To make integrations as easy as possible, the Code in this API Endpoint is the Code/ID of any Google, Bing, Facebook, or LinkedIn campaign that is tied to a data source within your account. To see a list of available objects, explore the reference documentation in the side navigation or try building a query in the Forge.
To request data over a specific date range, start and end dates can be provided as API parameters. If no date parameters are given, the data is returned month to date. Requests with date ranges have the following form:
{
status: "success",
message: "",
errors: null,
data: {
campaigns: {
code_campaign: "14140888783"
}
}
}
To make integrations as easy as possible, the Code in this API Endpoint is the Code of any Google, Bing, Facebook, or LinkedIn campaign code that is tied to a data source within your account. To see a list of available objects, explore the reference documentation in the side navigation or try building a query in the Forge.
The selection of fields returned from an object can be set directly in the fields parameter:
{
status: "success",
message: "",
errors: null,
data: {
campaigns: {
name_campaign: "Campaign 1",
clicks: 344,
conversions: 25
}
}
}
A complete list of available fields for each object can be found in the reference documentation.
A key feature of the Shape API’s graph-based interface is nested queries. Nested queries allow developers to request all the data they need in a single query. For example, when querying a campaign, instead of making a separate request, simply include adgroups as an additional field when querying the campaign.
{
status: "success",
message: "",
errors: null,
data: {
campaigns: {
name_campaign: "Campaign 1",
clicks: 344,
conversions: 25,
adgroups: [
{
name_adgroup: "Ad Group 1",
cost: 2.44,
clicks: 1,
conversions: 0
},
{
name_adgroup: "Ad Group 2",
cost: 92.11,
clicks: 77,
conversions: 6
},
{
name_adgroup: "Ad Group 3",
cost: 58.32,
clicks: 68,
conversions: 7
},
{
name_adgroup: "Ad Group 4",
cost: 21.82,
clicks: 38,
conversions: 1
},
{
name_adgroup: "Ad Group 5",
cost: 120.72,
clicks: 160,
conversions: 11
}
]
}
}
}
These requests can be nested to any depth, providing the developer with maximum flexibility:
{
status: "success",
message: "",
errors: null,
data: {
campaigns: {
name_campaign: "Campaign 1",
clicks: 344,
conversions: 25,
adgroups: [
{
name_adgroup: "Ad Group 1",
cost: 2.44,
clicks: 1,
conversions: 0,
keywords: [
{
criteria: "+keyword +one",
cost: 0,
clicks: 0
},
{
criteria: "+keyword +two",
cost: 0,
clicks: 0
},
{
criteria: "+keyword +three",
cost: 0,
clicks: 0
},
{
criteria: "+keyword +four",
cost: 0,
clicks: 0
},
{
criteria: "+keyword +five",
cost: 2.44,
clicks: 1
}
]
},
{
name_adgroup: "Ad Group 2",
cost: 92.11,
clicks: 77,
conversions: 6,
keywords: [
{
criteria: "+keyword +one",
cost: 45.12,
clicks: 32
},
{
criteria: "+keyword +two",
cost: 18.00,
clicks: 11
},
{
criteria: "+keyword +three",
cost: 19.90,
clicks: 18
},
{
criteria: "+keyword +four",
cost: 9.09,
clicks: 17
}
]
},
{
name_adgroup: "Ad Group 3",
cost: 58.32,
clicks: 68,
conversions: 7,
keywords: [
{
criteria: "+keyword +one",
cost: 58.32,
clicks: 68
}
]
},
{
name_adgroup: "Ad Group 4",
cost: 21.82,
clicks: 38,
conversions: 1,
keywords: [
{
criteria: "+keyword +one",
cost: 21.82,
clicks: 38
}
]
},
{
name_adgroup: "Ad Group 5",
cost: 120.72,
clicks: 160,
conversions: 11,
keywords: [
{
criteria: "+keyword +one +expanded",
cost: 8.21,
clicks: 14
},
{
criteria: "+keyword +two +expanded",
cost: 31.98,
clicks: 41
},
{
criteria: "+keyword +three +expanded",
cost: 0,
clicks: 0
},
{
criteria: "+keyword +four +expanded",
cost: 63.90,
clicks: 86
},
{
criteria: "+keyword +five",
cost: 15.91,
clicks: 19
}
]
}
]
}
}
}
Data segmentations for a given object are accessed the same way as associations. Segmentations can be identified as the associations whose names are all prefixed with an underscore such as _daily, _network, and _device.
{
status: "success",
message: "",
errors: null,
data: {
campaigns: {
name_campaign: "Campaign 1",
clicks: 344,
conversions: 25,
_device: [
{
device: "Computer",
clicks: 312
},
{
device: "Smartphone",
clicks: 28
},
{
device: "Tablet",
clicks: 4
}
]
}
}
}