Introduction
The Marketing Solutions APIs are a suite of APIs that enable you to manage the building and deployment of Proximity and Audience designs.
Lifecycle
The basic lifecycle of a Proximity/Audience design is as follows:
- A user creates and saves a design using Foursquare Targeting’s authoring tools. At this point, a design id is generated.
- The user requests that the design be built. At this point, a build id is generated.
- Foursquare Targeting processes the build request.
- Using information contained in the Proximity or Audience design, Foursquare Targeting generates a targeting file, known as a Proximity Filter or Audience Set, respectively.
- These targeting files are used in conjunction with Foursquare Targeting’s On-Prem software to provide real time targeting information.
- Once the build is successfully processed, the design is now associated with an available build.
- The user requests a deployment of that build to a given partner’s On-Prem software. At this point, a deployment id is generated.
- An administrator of the On-Prem software approves the deployment request and activates the deployment.
- Upon activation, the targeting file associated with the deployment will get loaded into memory in the partner’s On-Prem software and responses from the targeting file will begin to be returned.
- When the campaign is complete, the administrator can deactivate or delete the deployment, removing the targeting file from their On-Prem software.
A few non-standard paths exist:
- After step 5 and before an administrator has completed step 6, the user that requested deployment of a built design may cancel their pending request.
- At step 6, the administrator may reject the activation request (e.g. if the targeting file associated with the deployment is abnormally large).
- At step 7, the administrator may tag a deployment for the purpose of optimizing server capacity.
- At step 7, the administrator may temporarily deactivate a build to free up memory in their On-Prem servers and then reactivate it when convenient.
API Overview
The following APIs enable programmatic access to each step of the aforementioned lifecycle:
Endpoint | Description |
---|---|
/geopulse/designs/design_id | Get meta-data for a specific design |
/geopulse/designs/ | List all designs visible to you |
/geopulse/designs/design_id/request | Request that a design be built by Foursquare Targeting |
/geopulse/builds | List designs that have been successfully built, build history, and deployment status |
/geopulse/builds/build_id/request | Request that a built design be activated |
/geopulse/deployments/deployment_id/cancel | Cancel an activation request before it is approved and activated |
/geopulse/deployments/deployment_id/reject | Reject a request to activate a build |
/geopulse/deployments/ | List deployments |
/geopulse/deployments/deployment_id/activate | Activate a build |
/geopulse/deployments/deployment_id/deactivate | Deactivate a build |
/geopulse/deployments/deployment_id/delete | Delete a build |
/geopulse/deployments/deployment_id/tag | Tag a deployed build (for capacity management) |
You will find comprehensive documentation on each API call below.
Each API call will include a number of standard response parameters,
Parameter Name | Description | Datatype | Example |
---|---|---|---|
version | The version of the API response | Number | 4 |
status | The status of the API response | String | "OK" |
**response | The response object | JSON Object | |
response.data | The data object, containing a single design object with the parameters found in the below "Response Data Parameters" | JSON Object | |
included_row_count | The total rows included in the data array contained in this response | Number | 23 |
total_row_count | The total rows available for this data array See paging | Number | 1002 |
Get Design
Returns all details about a specific Proximity or Audience design.
Endpoint
https://api.targeting.foursquare.com/geopulse/designs/(design Id)
- This endpoint only accepts GET requests.
- Replace (design Id) with the id of the design for which you are requesting information.
Example
https://api.targeting.foursquare.com/geopulse/designs/24e12f0e-ab5f-47e0-8b7d-a7ce63241068?KEY=your_api_key
Request Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
*Key | Your API Key. Note the KEY parameter name must be declared in all caps. | String | KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c |
*Required
Response Data Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
id | The design ID | String (GUID) | "38697e15-9e9e-4917-b55b-6431b99392f4" |
name | The design name | String | "LA Car Dealerships" |
type | proximity or audience | String (enumerated) | "proximity" |
status | in_design, requested, rejected, building, failed, built | String (enumerated) | "in_design" |
created_at | Timestamp for when design was created | String (date) | "2016-01-06T17:11:17.000Z" |
updated_at | Timestamp of most recent design update | String (date) | "2016-01-06T17:11:17.000Z" |
external_build | Whether or not the design is associated with a build created outside of the designer tools. A design with a value of "true" cannot be edited. | Boolean | false |
design_size | (Deprecated) An internal value that estimates how complex this design may be to build on a relative scale. Not intended to be user facing. | Number | 12 |
most_recent_build | The build ID of the most recent build | String (GUID) | "ac5925c7-e727-45b5-848b-c2532dc84db7" |
owner_id | The user id of the design's owner | String (GUID) | "eea9f6ef-c9f3-430a-8db0-d89e8476aebd" |
owner_org_id | The id of the design owner's organization | String (GUID) | "d4e49049-07fd-4c67-8325-1c803a8d1857" |
owner_name | The email of the design owner | String | " |
price_cpm | Price of the design in CPM. Base represents the price of this design when used to target impressions from most countries. Additional regional variations are coming soon. | JSON Object | {"base": "0.75"} |
active_builds | The number of builds associated with this design that have been deployed to a partner's On-Prem software | Number | 1 |
is_shared_to_current_user | Whether access to the design has been explicitly shared with the current user | Boolean | false |
is_shared_to_current_org | Whether access to the design has been shared with the current user's entire organization | Boolean | false |
sets | An array of sets contained within the design object | JSON Array | |
sets[row].set_id | The id of the set | String (GUID) | "d151ea2c-9879-460c-a169-77a0de9ec3c5" |
sets[row].set_name | The name of the set | String | "Used Car Dealers" |
sets[row].targeting_code | The targeting code associated with the set | String | "cars_1000m" |
set_ids | An array of all set IDs associated with the design | JSON Array | |
collaborators | An array of all users or orgs explicitly granted access to the design | JSON Array | |
collaborators[row].type | user or org | String | "user" |
collaborators[row].id | The user or org ID of the collaborator | String (GUID) | "eea9f6ef-c9f3-430a-8db0-d89e8476aebd" |
collaborators[row].label | The human readable representation of the user or org. Email for user. Org Name for org. | String | " |
collaborators[row].permissions | Permissions defining the collaborator's level of access to the design | JSON Object | |
collaborators[row].permissions[row].view | Whether or not the collaborator has access to view the design | Boolean | true |
collaborators[row].permissions[row].edit | Whether or not the collaborator has access to edit the design | Boolean | true |
Design Status Enumeration
Design Status | Description | Design Editable? | Can Request Build? |
---|---|---|---|
in_design | The design is in the design phase and has not been requested or built yet. | Yes | Yes |
requested | The user has requested a build get created from the design, and it is awaiting being places onto Foursquare Targeting's cluster to process the build. The design is frozen in this state, and cannot be changed until the build successfully completes or the build request is rejected. | No | No |
rejected | The build request was rejected by Foursquare Targeting, and must be re-requested. The design is free to be edited in this state. | Yes | Yes |
building | The design is in Foursquare Targeting's cluster queue to be processed into a build. | No | No |
failed | The build process failed, and Foursquare Targeting will either fix the build and re-try or reach out to make any necessary fixes. | No | No |
built | The design has been successfully built. | Yes | Yes |
List Designs
Returns all details about any Proximity or Audience designs for which you have been granted visibility.
Endpoint
https://api.targeting.foursquare.com/geopulse/designs/
- This endpoint only accepts GET requests.
Example
https://api.targeting.foursquare.com/geopulse/designs?type=proximity&KEY=your_api_key
Request Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
limit | When paging through longer lists of data, the maximum number of rows to return per request. See paging | Number | limit=10 |
offset | When paging through longer lists, the offset from the first row of data to begin at. See paging | Number | offset=0 |
owner | The user ID of the user that created the design.1 | String (GUID) | owner=eea9f6ef-c9f3-430a-8db0-d89e8476aebd |
owner_org_id | The organization ID of the user that owns the design. | String (GUID) | owner_org_id=d4e49049-07fd-4c67-8325-1c803a8d1857 |
q | A full-text search string. | String | q=car |
type | The type of design. Either proximity or audience. | String (enumerated) | type=audience |
visibility | Filter out designs that do not contain the granted visibility tags | Comma delimited array of Strings | visibility=star_market,pepsi |
*KEY | Your API Key. Note the KEY parameter name must be declared in all caps. | String | KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c |
*Required
1On rare occassions, a design may be administratively assigned ownership to a different user than the one who created it. For example, if a user was to leave an org.
Response Data Parameters
For a full description of all parameters available in each row of this data object, see Get Design: Response Data Parameters above.
Request Build of a Design
Sends a request to Foursquare Targeting that this design be processed and a targeting file be produced from it. Requesting a build will put the design into status “requested” and render the design un-editable until the build is either completed or rejected by Foursquare Targeting. Note that a request build call is only valid for designs of status “in_design”, “rejected”, or “built”. For more information on design status, please see Get Design: Design Status Enumeration above.
Endpoint
https://api.targeting.foursquare.com/geopulse/designs/(design id)/request
- This endpoint only accepts POST requests.
- Replace (design id) with the id of the design you are requesting a build for.
- Request Parameters should be URL encoded and POSTed as the body of the request.
- The Content-Type for this request should be set to application/x-www-form-urlencoded.
Example
POST /geopulse/designs/7e805739-34c2-43d8-b19c-965b2a19b715/request HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 81
reason=require+asap&KEY=your_api_key
Request Parameters
Parameter Name | Description | Datatupe | Example |
---|---|---|---|
*reason | A text description of the reason for this build request | String | reason=testing |
*KEY | Your API Key. Note the KEY parameter name must be declared in all caps. | String | KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c |
*Required
Response parameters
If the build request was successful, it will return with a status "OK"
List Builds
Returns a list of all designs that have been successfully built, along with the build history and current deployment status of each design.
Endpoint
https://api.targeting.foursquare.com/geopulse/builds
- This endpoint only accepts GET requests.
Example
https://api.targeting.foursquare.com/geopulse/builds?type=audience&deployment_status=activated&KEY=your_api_key
Request Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
limit | When paging through longer lists of data, the maximum number of rows to return per request. See paging | Number | limit=10 |
offset | When paging through longer lists, the offset from the first row of data to begin at. See paging | Number | offset=0 |
q | A full-text search string. | String | q=car |
type | The type of design. Either proximity or audience. | String (enumerated) | type=audience |
visibility | Filter out designs that do not contain the granted visibility tags | Comma delimited array of Strings | visibility=coke visibility=star_market,pepsi |
deployment_status | The builds current deployment status: activated, deactivated, requested, requested_replacement, out_of_date, or undeployed. For a full description of the various deployment statuses, see Deployment Status Filter Enumeration below. | Comma delimited array of strings | deployment_status=activated,deactivated |
deployment_target | The slug of the target org to which the deployment_status parameter should be applied. Does nothing if deployment_status is not specified. | Comma delimited array of strings | deployment_target=bigdsp |
min_size | Minimum size of the targeting file associated with the most recent build | Number | min_size=10000 |
max_size | Maximum size of the targeting file associated with the most recent build | Number | max_size=10000000 |
sort | Sort by build_date, requested_at, or last_build_size | String (enumerated) | sort=last_build_size |
*KEY | Your API Key. Note the KEY parameter name must be declared in all caps. | String | KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c |
*Required
Response Data Row Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
id | The design ID | String (GUID) | "38697e15-9e9e-4917-b55b-6431b99392f4" |
type | proximity or audience | String (enumerated) | "proximity" |
name | The design name | String | "LA Car Dealerships" |
owner | Email of the design owner | String | " |
builds | Array of build objects associated with this design | JSON Array | |
builds[row].id | Build ID | String (GUID) | "a4d51e3b-ae95-4917-a7db-878255f334ea" |
builds[row].name | Name of the build. This is equal to the design name at the point that the build is initially generated. | String | "LA Automotive" |
builds[row].status | The processing status of the build. Currently will only return DONE | String (enumerated) | "DONE" |
builds[row].size | Size, in bytes, of the targeting file associated with the completed build | Number | 1061822 |
builds[row].requested_at | Timestamp representing when the build was initially requested | String (date) | "2016-02-29T22:26:26.000Z" |
builds[row].build_date | Timestamp representing when the build was successfully completed | String (date) | "2016-03-01T05:22:33.000Z" |
builds[row].builder | Email of the user who requested the build | String | " |
builds[row].source (DEPRECATED) | The inventory source (e.g. ad exchange) that was used to create the build object. Only returned for designs of type "audience" where an inventory source must be specified. | String | "factual_dap" |
builds[row].sources | The inventory source(s) (e.g. ad exchanges) that were used to create the build object. Only returned for designs of type "audience" where an inventory source must be specified. | JSON Array | ["factual_dap", "ad_corp"] |
builds[row].audience_index_version | Date that the inventory source used to create the build was last processed | String (date) | "2016-02-29T22:26:26.000Z" |
builds[row].price_cpm | Price of the design in CPM. Base represents the price of this design when used to target impressions from most countries. Additional regional variations are coming soon. | JSON Object | {"base": "0.75"} |
deployments | Array of deployment objects associated with this design | JSON Array | |
deployments[row].id | Deployment ID | String (GUID) | "5ca6f818-7a0e-429d-9fcf-1c72d7ca1b3b" |
deployments[row].target | Name of the target where this deployment is associated | String | "Big DSP" |
deployments[row].target_id | ID of the target where this deployment is associated | String (GUID) | "42dc6d44-a910-4e11-8fdb-8051c10aadee" |
deployments[row].status | Status of the deployment activated, deactivated, requested | String (enumerated) | "activated" |
deployments[row].build_id | Build ID of the build object associated with this deployment | String (GUID) | "a4d51e3b-ae95-4917-a7db-878255f334ea" |
last_build_id | Build ID for the most recent build of this design | String (GUID) | "a4d51e3b-ae95-4917-a7db-878255f334ea" |
last_build_name | Name of the most recent build of this design | String | "LA Automotive" |
last_build_builder | Email of the user who requested the most recent build of this design | String | " |
last_build_date | Timestamp of when the most recent build of this design was completed | String (date) | "2016-03-01T05:22:33.000Z" |
last_build_source (DEPRECATED) | Inventory source of the most recent build of this design | String | "factual_dap" |
last_build_sources | Inventory source(s) of the most recent build of this design | JSON Array | ["factual_dap", "ad_corp"] |
last_build_size | Size in bytes of the targeting file associated with the most recent build of this design | Number | 110292 |
last_build_audience_index_version | Date that the inventory source used to create the build was last processed | String (date) | "2016-02-29T22:26:26.000Z" |
Deployment Status Filter Enumeration
Deployment Status Filter | Description |
---|---|
activated | Return any designs with a deployment that is "activated" on the target partner's system |
deactivated | Return any designs with a deployment that is temporarily "deactivated" the target partner's system (e.g. to conserve memory on the partner's servers) |
requested | Return any designs with a deployment that is "requested" on the target partner's system, where that deployment has not been activated or rejected yet. |
requested_replacement | Return any designs that have a deployment that is "requested" which, if activated, will replace an existing deployment associated with that design. A design can only have a single build activated on a given partner's system at any given time. |
out_of_date | Return any designs that have a deployment on the target partner's system where the build associated with that deployment is out of date, and a more recent build has since been generated. (e.g. Design ABC has been built 5 times, but only build 4 is deployed to a partner) |
undeployed | Return any designs that have no deployment associated with the target partner's system. |
Request Deployment of a Built Design
Request that a build be deployed to a partner's infrastructure. Note that this API represents a request to a Geopulse Administrator who must subsequently activate the request (or reject it). If a build already has an associated deployment on a given target org's infrastructure, it cannot be requested to that org. For a single design, only one build may have an activated deployment on a given target org's infrastructure at any time (e.g. if Design XYZ has 4 builds, a given target org can only have one of those builds deployed at any time.)
Geopulse Administrators can see pending requests by using the deployment list API.
Endpoint
https://api.targeting.foursquare.com/geopulse/builds/(build id)/request
- This endpoint only accepts POST requests.
- Replace (build Id) with the id of the build for which you are requesting activation.
- Request Parameters should be URL encoded and POSTed as the body of the request.
- The Content-Type for this request should be set to application/x-www-form-urlencoded.
Example
POST /geopulse/builds/03c26917-5d66-4de9-96bc-b13066173c65/request HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 104
message=this+is+for+a+geotargeting+campaign&targetId=fc873d35-6f59-4d41-822a-254b716d8532&KEY=your_api_key
Request Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
message | A message to send with the deployment request if you would like Foursquare Targeting to know additional metadata | String | message=this+is+a+test |
*targetId | The ID of the deployment target that the user is wanting to deploy to | String (GUID) | targetId=fc873d35-6f59-4d41-822a-254b716d8532 |
*KEY | Your API Key. Note the KEY parameter name must be declared in all caps. | String | KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c |
*Required
Response Parameters
If the deployment request was successful, it will return with a status "OK"
Cancel a Deployment Request
Cancel a pending deployment request. This API is intended to support cancellation of a deployment request by the user who initiated the request. Only requests which have not already been either activated or rejected can be cancelled.
Endpoint
https://api.targeting.foursquare.com/geopulse/deployments/(deployment id)/cancel
- This endpoint only accepts POST requests.
- Replace (deployment id) with the id of the design you are requesting a build for.
- Request Parameters should be URL encoded and POSTed as the body of the request.
- The Content-Type for this request should be set to application/x-www-form-urlencoded.
Example
POST /geopulse/deployments/8d7d2d1f-7ee8-428e-9d27-23d7cfbf6c5d/cancel HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 67
message=apologies%2C+but+this+was+the+wrong+build&KEY=my_api_key
Request Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
message | A message to send with the deployment cancellation if you would like Foursquare Targeting to know additional metadata | String | message=wrong+partner |
*KEY | Your API Key. Note the KEY parameter name must be declared in all caps. | String | KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c |
*Required
Response Parameters
If the deployment request cancellation was successful, it will return with a status "OK"
List Deployments
The Deployment List API returns a list of all builds that have been deployed across your infrastructure, whether they are activated, deactivated, or requested. To return only a list of requested deployments, add the filter "status=requested" to this call. Similarly, to return only a list of activated deployments, add the filter "status=activated"
Endpoint
https://api.targeting.foursquare.com/geopulse/deployments
- This endpoint only accepts GET requests.
Example
https://api.targeting.foursquare.com/geopulse/deployments?type=proximity&status=activated&KEY=my_api_key
Request Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
limit | When paging through longer lists of data, the maximum number of rows to return per request. See paging | Number | limit=10 |
offset | When paging through longer lists, the offset from the first row of data to begin at. See paging | Number | offset=0 |
q | A full-text search string. | String | q=car |
type | The type of design. Either proximity or audience. | String (enumerated) | type=audience |
target_type | The type of target the deployment is associated with (e.g. OnPrem, LIDS, etc.) | String | target_type=onprem |
visibility | Filter out designs that do not contain the granted visibility tags | Comma delimited array of Strings | visibility=coke visibility=star_market,pepsi |
status | Status of the deployment: activated, deactivated, or requested. | Comma delimited array of strings | status=activated,deactivated |
min_size | Minimum size of the targeting file associated with deployed build | Number | min_size=10000 |
max_size | Maximum size of the targeting file associated with deployed build | Number | max_size=10000000 |
start_date | Starting timestamp to filter deployments by time of approval. | Integer (epoch date, seconds) | start_date=1475167405 |
end_date | Ending timestamp to filter deployments by time of approval. | Integer (epoch date, seconds) | end_date=1475167424 |
new_build | Filter by the following: true=deployments associated with the first build of a design, false=deployments associated with a refreshed build | Boolean | new_build=true |
sort | Sort by updated_at, approved_at, build_date, or build_size | String (enumerated) | sort=build_size |
*KEY | Your API Key. Note the KEY parameter name must be declared in all caps. | String | KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c |
*Required
Response Data Row Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
id | The deployment ID | String (GUID) | "5ca6f818-7a0e-429d-9fcf-1c72d7ca1b3b" |
status | Status of the deployment: activated, deactivated, or requested. | "activated" | |
type | proximity or audience | String (enumerated) | "proximity" |
design_id | ID of the associated design | String (GUID) | "38697e15-9e9e-4917-b55b-6431b99392f4<"/pre> |
build_id | The build ID | String (GUID) | "a4d51e3b-ae95-4917-a7db-878255f334ea" |
design_name | The current name of the design. | String | "LA Car Dealerships" |
build_name | Name of the build | String | "LA Automotive" |
filesize | Size, in bytes, of the targeting file associated with the deployed build | Number | 1061822 |
source (DEPRECATED) | The inventory source (e.g. ad exchange) that was used to create the build object. Only applicable to designs of type "audience" where an inventory source must be specified to determine what inventory source to create the audience off of. Null for builds associated with designs of type "proximity". | String | "factual_dap" |
sources | The inventory source(s) (e.g. ad exchange) that was used to create the build object. Only applicable to designs of type "audience" where an inventory source must be specified to determine what inventory source(s) to create the audience off of. Null for builds associated with designs of type "proximity". | JSON Array | ["factual_dap", "ad_corp"] |
price_cpm | Price of the design in CPM. Base represents the price of this design when used to target impressions from most countries. Additional regional variations are coming soon. | JSON Object | {"base": "0.75"} |
build_org | Slug of the Org associated with the user who generated the build | String | "factual" |
build_org_id | ID of the Org associated with the user who generated the build | String (GUID) | "9303c65c-ad1f-4845-837f-aa87197cd448" |
builder | Email of the user who generated the build | String | " |
requester | Email of the user who requested the deployment | String | " |
deployer | Email of the Geopulse admin who approved the deployment request | String | " |
build_date | Timestamp representing when the build was successfully completed | String (date) | "2016-03-01T05:22:33.000Z" |
updated_at | Timestamp representing when the deployment was most recently updated | String (date) | "2016-03-03T00:45:30.000Z" |
approved_at | Timestamp representing when the deployment was initially marked as activated | String (date) | "2016-03-03T00:45:30.000Z" |
new_build | Describes whether a deployment is associated with the first build of a given design. True = first version of a design | Boolean | true |
tags | Deployment tags associated with the deployment | String | "large,europe" |
target | Name of the target associated with the deployment | String | "Big DSP OnPrem" |
target_id | ID of the deployment target | String (GUID) | "aaffc17d-fd80-34aa-22bc-32133edf88b1" |
sets | Array of sets in the build associated with the deployment | JSON Array | |
sets[row].set_id | The id of the set | String (GUID) | "d151ea2c-9879-460c-a169-77a0de9ec3c5" |
sets[row].set_name | The name of the set | String | "Used Car Dealers" |
sets[row].targeting_code | The targeting code associated with the set | String | "cars_1000m" |
Reject a Requested Deployment
Reject a deployment request. This may be used in the event that a Geopulse Admininistrator considers the targeting file associated with a deployment request to be too large for their infrastructure. Only deployments with status “requested” may be rejected.
Endpoint
https://api.targeting.foursquare.com/geopulse/deployments/(deployment id)/reject
- This endpoint only accepts POST requests.
- Replace (deployment Id) with the deployment id.
POST /geopulse/deployments/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/reject HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 14
KEY=my_api_key
Request Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
*KEY | Your API Key. Note the KEY parameter name must be declared in all caps. | String | KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c |
*Required
Response Parameters
If the deployment rejection is successful, the call will return a status of "OK"
Activate a Deployment
Activate a deployment. Any deployment may be activated, except for those with status "activated" already.
Endpoint
https://api.targeting.foursquare.com/geopulse/deployments/(deployment id)/activate
- This endpoint only accepts POST requests.
- Replace (deployment Id) with the deployment id.
Example
POST /geopulse/deployments/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/activate HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26
KEY=my_api_key
Request Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
*KEY | Your API Key. Note the KEY parameter name must be declared in all caps. | String | KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c |
*Required
Response Parameters
If the deployment activation is successful, the call will return a status of "OK"
Deactivate a Deployment
Deactivate a deployment, temporarily removing it from an On-Prem instance. This endpoint is provided to support lightweight toggling of deployed builds between active and inactive states. Only deployments of status "activated" can be deactivated.
Endpoint
https://api.targeting.foursquare.com/geopulse/deployments/(deployment id)/deactivate
- This endpoint only accepts POST requests.
- Replace (deployment Id) with the deployment id.
Example
POST /geopulse/deployments/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/deactivate HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 14
KEY=my_api_key
Request Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
*KEY | Your API Key. Note the KEY parameter name must be declared in all caps. | String | KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c |
*Required
Response Parameters
If the deployment deactivation is successful, the call will return a status of "OK"
Delete a Deployment
Delete a deployment, removing it permanently from an On-Prem server. At their core, “deactivate” and “delete” fulfill the same function, which is to remove a targeting file from memory on an On-Prem server, but where “deactivated” deployments will still show up in the Geopulse Management API results, “deleted” deployments do not show up, and should be considered as gone forever. Deleting deployments is primarily for situations where the end user or Geopulse Administrator know that this particular deployment will not be needed again, and deleting it (as opposed to deactivating it) can help to declutter the API results.
Endpoint
https://api.targeting.foursquare.com/geopulse/deployments/(deployment id)/delete
- This endpoint only accepts POST requests.
- Replace (deployment Id) with the deployment id.
Example
POST /geopulse/deployments/e1fea89d-cdeb-43b7-b5a7-e272920ca1d8/delete HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 14
KEY=my_api_key
Request Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
*KEY | Your API Key. Note the KEY parameter name must be declared in all caps. | String | KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c |
*Required
Response Parameters
If the deployment deletion is successful, the call will return a status of "OK"
Tag a Deployment
Deployment tags, when used in conjunction with Geopulse On-Prem software, can help with server capacity management. At set up time, an On-Prem owner can define for any individual On-Prem server which deployment tags that server should be associated with. In this case, only targeting files associated with deployments that have the matching deployment tags will be loaded into memory on the particular On-Prem server. This can help to reduce required memory on your servers, as each server no longer needs to load every targeting file.
Adding deployment tags is destructive of previous tags, so making this call will always overwrite the earlier list of tags.
Endpoint
https://api.targeting.foursquare.com/geopulse/deployments/(deployment id)/tag
- This endpoint only accepts POST requests.
- Replace (deployment id) with the id of the design you are requesting a build for.
- Request Parameters should be URL encoded and POSTed as the body of the request.
- The Content-Type for this request should be set to application/x-www-form-urlencoded.
Example
POST /geopulse/deployments/89aa8acb-4563-4817-9051-2424aa632f20/tag HTTP/1.1
Host: api.targeting.foursquare.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 26
tags=env1&KEY=my_api_key
Request Parameters
Parameter Name | Description | Datatype | Example |
---|---|---|---|
*tags | The defined deployment tags | String (comma delimited) | tags=large,europe |
*KEY | Your API Key. Note the KEY parameter name must be declared in all caps. | String | KEY=1Z88ulxbtb3jZnV7Gqlm9AcPwM6OojtSGbv98t6c |
*Required
Response Parameters
If the tag assignment is successful, the call with return a status of "OK"
Common Conventions
Paging
For API calls that return large volumes of data, the Foursquare Targeting API implements a paging system. Each API call will return one "page" of data, which includes a limited number of rows of data, offset from the start of the entire list of available data.
For example:
- The first 10 rows would be identified by limit=10 and offset=0.
- The next 10 rows would be identified by limit=10 and offset=10.
Paging parameters are used in conjunction with any other parameters that may filter a list down. So, for example, if you request a list of designs filtered to just proximity designs, you'll get the first 10 proximity designs, then the next 10. There won't be any "holes" in the result set where audience designs would have slotted chronologically.