API
URL: http://<hostname>/geo/remote/rest/location/modify
HTTP Method(s): POST
Create or update locations. If the request successfully creates a new location or successfully updates a location, a serial number will be returned. Otherwise, the raw location error contains information about the cause of the error, including potential candidates to choose from.
To create a location, the following attributes are required: code (your identifier for this location), name, geocode, and address information. However, by providing additional attributes like category, brand, and phone number for a location, you increase your chances of matching to this location later.
To update a location, the following attributes are required: code (your identifier for this location) OR serial number plus the field(s) that you want to update.
Example
Request:
v=<version>
k=<key>
f=xml
location.code=1020_PLACECAST
location.name=1020 Placecast
location.geoLocation.geocode.latitude=37.773831
location.geoLocation.geocode.longitude=-122.4235
location.geoLocation.address.address1=165 Page St
location.geoLocation.address.region1=San Francisco
location.geoLocation.address.region2=CA
location.geoLocation.address.postalCode=94102
location.geoLocation.address.countryCode=US
location.category.code=2_technology_company
location.brand.code=placecast
location.primaryPhoneNumber=4155221020
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<locationModifyResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1">
<infoMessage>
<key>locationUpdatedSuccessfully</key>
<text>Location edited successfully</text>
</infoMessage>
</responseHeader>
<serialNumber>1100300005</serialNumber>
<newLocation>false</newLocation>
</locationModifyResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| location | Location | Y | The modified location. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
| serialNumber | Long | The serial number associated with the location. If the location has just been created, then the serial number provides a useful link to access the new location. |
| newLocation | Boolean | The indicator as to whether the location was created. A false value indicates that the record was updated. |
| rawLocationError | RawLocationError | Information describing any errors that occurred during processing, including potential fixes. |
Error handling
If there are errors processing inbound requests, they generally fall into one of the categories illustrated in the workflow below.
URL: http://<hostname>/geo/remote/rest/location/setNew
HTTP Method(s): POST
Workflow service method to mark the errored modify request as a valid new location.
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| ticketNumber | Long | Y | The ticket number provided in the modify location error . |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/location/selectCandidate
HTTP Method(s): POST
Workflow service method to select a location from a set of returned candidates.
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| ticketNumber | Long | Y | The ticket number provided in the modify location error response. |
| serialNumber | Long | Y | The serial number of the location. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
Example with error handling
Initial request:
v=<version>
k=<key>
f=xml
location.code=PLACECAST
location.name=Placecast
location.geoLocation.geocode.latitude=37.774
location.geoLocation.geocode.longitude=-122.423
location.geoLocation.address.address1=165 Page St
location.geoLocation.address.region1=San Francisco
location.geoLocation.address.region2=CA
location.geoLocation.address.postalCode=94102
location.geoLocation.address.countryCode=US
Response with error due to potential duplicate:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<locationModifyResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1">
<errorMessage>
<key>locationModifyFailed</key>
<text>Error(s) modifying Location</text>
</errorMessage>
</responseHeader>
<serialNumber xsi:nil="true" xmlns:xsi="http://www.w3..."/>
<newLocation>false</newLocation>
<rawLocationError>
<ticketNumber>3842246</ticketNumber>
<jobNumber>15415337034830405</jobNumber>
<errorMessages>
<key>foundDuplicateLocations</key>
<text>Found a possible Location match</text>
<errorType>
<code>CANDIDATE_LOCATIONS</code>
<name>Candidate Locations</name>
</errorType>
</errorMessages>
<candidateLocation>
<serialNumber>1100300005</serialNumber>
<name>1020 Placecast</name>
<geoLocation>
<address xsi:type="inputAddress" xmlns:xsi="http://www.w3...">
<addressType>
<code>STREET_ADDRESS</code>
<name>Street Address</name>
</addressType>
<countryCode>US</countryCode>
<address1>165 PAGE ST</address1>
<region1>SAN FRANCISCO</region1>
<region2>CA</region2>
<postalCode>94102</postalCode>
</address>
<geocode>
<latitude>37.773829</latitude>
<longitude>-122.4234</longitude>
</geocode>
</geoLocation>
</candidateLocation>
</rawLocationError>
</locationModifyResponse>
Follow-up request to select a candidate:
v=<version>
k=<key>
f=xml
ticketNumber=123
serialNumber=1100300005
Successful response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rawLocationSelectCandidateLocationResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1">
<infoMessage>
<key>locationUpdatedSuccessfully</key>
<text>Location edited successfully</text>
</infoMessage>
</responseHeader>
<serialNumber>1100300005</serialNumber>
<newLocation>false</newLocation>
</rawLocationSelectCandidateLocationResponse>
Error types
Inbound data that's flagged for review is grouped into the following error types:
| Error Type | Description |
| Not Authorized | User does not have the appropriate system permissions to perform this action. Example: User attempts to create a location but doesn't have the permissions to do so. |
| Required Data Missing | The record being imported or edited is missing required field(s). Example: User attempts to create a location without populating "name." |
| Invalid Action | The attempted action is not possible. Example: Attempt to update or delete a location that does not exist in the repository. |
| Invalid Syntax | There is an issue related to a Data Type mismatch within the record being modified. Example: Inbound data contains characters in a field that requires numeric data. |
| Invalid Identifier | Any problem that involves modifying or importing a record using invalid codes or types. Example: Inbound data contains invalid category or brand code. |
| Invalid Semantics | Any problem that involves modifying or importing data in a way that is logically inconsistent. Example: Inbound data contains a record with latitude but no longitude. |
| Unresolvable Address | The address on the record being modified or imported cannot be resolve to a valid GeoLocation. This means that the address could not be handled by the geocoder. Example: Inbound data contains a record with an invalid address such as Any-Town, Any-State, USA. |
| Modified Address | The record being imported has a potential ID or address conflict. Example: The record being imported has a potential ID or address conflict. |
| Candidate Address | Inbound data resolves to a candidate GeoLocation. Example: The inbound address data is represented as "100 Main St" and the following GeoLocations candidates are presented: "100 N Main St", "100 S Main St." |
| Candidate Locations | The inbound data has potential Location Candidate matches. Example: Inbound data is a potential match to a location, but is not a definitive one. |
| Duplicate in Namespace | The imported record was previously loaded by this user, but with a different CODE (identifier). |
| Unspecified | The error does not fall within one of the above mentioned basic error types. |
URL: http://<hostname>/geo/remote/rest/location/delete
HTTP Method(s): POST
Indicate that this location is no longer valid. A call to this method does not actually delete the record, but flags it for review.
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| serialNumber | Long | Y | The serial number of the location. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/location
HTTP Method(s): GET, POST
Pass in a combination of query keyword, filters and proximity centroid to the get location service method. In return, you'll receive location(s) from your account that match your search request.
Example
Request:
v=<version>
k=<key>
f=xml
searchCriteria.query=Placecast
proximityCriteria.center.latitude=37.773831
proximityCriteria.center.longitude=-122.4235
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<locationGetResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
<location>
<serialNumber>1100300005</serialNumber>
<code>1020_PLACECAST</code>
<name>1020 Placecast</name>
<tag>location</tag>
<tag>place</tag>
<tag>lbs</tag>
<tag>lba</tag>
<category>
<categoryType>
<code>PRIMARY_LOCATION</code>
<name>Primary Location</name>
</categoryType>
<code>technology_company</code>
<name>Business Services - Technology Company</name>
<level>2</level>
<parent>
<categoryType>
<code>PRIMARY_LOCATION</code>
<name>Primary Location</name>
</categoryType>
<code>business_services</code>
<name>Business Services</name>
<level>1</level>
</parent>
</category>
<brand>
<code>placecast</code>
<name>Placecast</name>
</brand>
<geoLocation>
<address xsi:type="inputAddress" xmlns:xsi="http://www.w3...">
<addressType>
<code>STREET_ADDRESS</code>
<name>Street Address</name>
</addressType>
<countryCode>US</countryCode>
<address1>165 PAGE ST</address1>
<region1>SAN FRANCISCO</region1>
<region2>CA</region2>
<postalCode>94102</postalCode>
<neighborhood>HAYES VALLEY</neighborhood>
</address>
<geocode>
<latitude>37.773831</latitude>
<longitude>-122.4235</longitude>
</geocode>
</geoLocation>
<primaryPhoneNumber>+1 (415) 522 1020</primaryPhoneNumber>
</location>
<listPager>
<listControl>
<startIndex>0</startIndex>
<segmentSize>10</segmentSize>
<segmentWindow>3</segmentWindow>
</listControl>
<startElement>1</startElement>
<endElement>1</endElement>
<currentSegment>1</currentSegment>
<previousSegments>0</previousSegments>
<nextSegments>0</nextSegments>
</listPager>
</locationGetResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| listControl | ListControl | N | The standard list paging control. |
| searchCriteria | SearchCriteria | N | The search criteria, which allows for searches by keywords and filters. |
| proximityCriteria | ProximityCriteria | N | The proximity criteria, which allows for searches around a specific latitutde and longitude. |
| serialNumber | List<Long> | N | The serial number of the location. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
| location | List<Location> | The locations matching the request. |
| listPager | ListPager | The standard list paging control. |
URL: http://<hostname>/geo/remote/rest/location/match
HTTP Method(s): GET, POST
Pass in a location identifier (code), namespace and the list of partner namespaces you are interested in. In return, you'll receive location reference(s) for the potential candidate matches.
Example
Request:
v=<version>
k=<key>
f=xml
namespace=twitter
code=2fd4329c29383a97
partnerNamespaces=foursquare,tms,citysearch
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<locationMatchResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
<serialNumber>1100704182</serialNumber>
<partnerLocationReference>
<namespace>tms</namespace>
<code>1100704182</code>
</partnerLocationReference>
<partnerLocationReference>
<namespace>citysearch</namespace>
<code>46289378</code>
</partnerLocationReference>
<partnerLocationReference>
<namespace>foursquare</namespace>
<code>24075</code>
</partnerLocationReference>
</locationMatchResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| serialNumber | Long | N | The serial number associated with the location. Required if namespace and code are not part of the request. |
| namespace | Code | N | The namespace to use when retrieving the location references. Required if serialNumber is not part of the request. |
| code | Code | N | The code associated with a location in a given namespace. Required if serialNumber is not part of the request. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
| partnerLocationReference | List<LocationReference> | The location references matching the request. |
URL: http://<hostname>/geo/remote/rest/content
HTTP Method(s): GET, POST
Pass in a combination of search criteria, content serial number, location serial number and content type. In return, you'll receive content from your account that matches your search request.
Example
Request:
v=<version>
k=<key>
f=xml
locationSerialNumber=1100300005
contentTypeCode=IMAGE
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<contentGetResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
<content>
<serialNumber>1100706713</serialNumber>
<code>1100706713</code>
<name>Placecast Logo</name>
<category>
<categoryType>
<code>PRIMARY_PRODUCT</code>
<name>Primary Product</name>
</categoryType>
<code>MISC</code>
<name>Miscellaneous</name>
<level>1</level>
</category>
<contentType>
<code>IMAGE</code>
<name>Image</name>
</contentType>
<contentLayout>
<x>300</x>
<y>250</y>
</contentLayout>
<contentBodyUrl>http://placecast.net/...jpg</contentBodyUrl>
</content>
<listPager>
<listControl>
<startIndex>0</startIndex>
<segmentSize>10</segmentSize>
<segmentWindow>3</segmentWindow>
</listControl>
<startElement>1</startElement>
<endElement>1</endElement>
<currentSegment>1</currentSegment>
<previousSegments>0</previousSegments>
<nextSegments>0</nextSegments>
</listPager>
</contentGetResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| listControl | ListControl | N | The standard list paging control. |
| searchCriteria | SearchCriteria | N | The search criteria, which allows for searches by keywords. |
| contentSerialNumber | Long | N | The serial number of the content. |
| locationSerialNumber | Long | N | The serial number of the location. |
| contentLayoutCode | Code | N | The code coresponding to the dimensions of the desired content e.g. 75x75, 300x250. |
| contentTypeCode | Code | N | The type of the content. e.g. IMAGE, REVIEW, EVENT. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
| content | List<Content> | The content matching the request. |
| listPager | ListPager | The standard list paging control. |
URL: http://<hostname>/geo/remote/rest/content/modify
HTTP Method(s): POST
Create or update content associated with a location.
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| content | Content | Y | The modified content. |
| media | Media | N | The binary media to associate with this content. |
| geofence | Geofence | N | The geofence associated with this content. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
| contentSerialNumber | Long | The serial number associated with the content. If the content has just been created, then the serial number provides a useful link to access the new content. |
| locationSerialNumber | Long | The serial number associated with the location. If the location has just been created, then the serial number provides a useful link to access the new location. |
URL: http://<hostname>/geo/remote/rest/content/delete
HTTP Method(s): POST
Indicate that this content is no longer valid.
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| serialNumber | Long | Y | The serial number of the content. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/optin
HTTP Method(s): GET, POST
Pass in a program, phone number and optional information such as location and email address. This will initiate the rest of the opt-in flow for that program.
Example
Request:
v=<version>
k=<key>
f=xml
phoneNumber=4151231234
programOwnerCode=PROG1
authorizeLocate=false
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<optInResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1">
<infoMessage>
<key>optInSuccessful<key>
<text>Opt-in successful<text>
</infoMessage>
</responseHeader>
</optInResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| programOwnerCode | Code | Y | The code for the participating program. |
| externalId | String (255) | N | A client/external identifier code for the registered user. |
| phoneNumber | PhoneNumber | Y | The mobile phone number of the opt-in user. |
| emailAddress | EmailAddress | N | The email address of the opt-in user. |
| address | InputAddress | N | Physical location of the opt-in user, for example a postal code or metro. |
| authorizeLocate | Boolean | N | The flag that determines whether a user has already opted-in to share location, or whether the platform should reach out for confirmation. |
| messageTemplate | String (60) | N | An optional opt-in message template that allows customization of the opt-in message sent to a subscriber. |
| optInCompleteDelay | Integer | N | Number of seconds to delay the opt-in complete SMS message after the initial-registration. This allows the user to receive the location-sharing message prior to the confirmation message. Default is 300 seconds(5 minutes). |
| locationSharingDelay | Integer | N | Number of seconds to delay the location sharing SMS message after the initial-registration. Default is 0 seconds. |
| locationSharingFirstReminderDelay | Integer | N | Number of seconds to delay the first location-sharing SMS message reminder for users who performed an initial registration but did not reply to the location-sharing message requesting access to use their location in the program. |
| locationSharingSecondReminderDelay | Integer | N | Number of seconds to delay the second and final location-sharing SMS message reminder for users who performed an initial registration but did not reply to the location-sharing message requesting access to use their location in the program. |
| preference.age | String (255) | N | Age of the opt-in user. e.g. preference.age=27 |
| preference.gender | String (255) | N | Gender of the opt-in user. e.g. preference.gender=MALE |
| preference.interestCategories | String (255) | N | User preferences as defined for a program. e.g. preference.interestCategories=sports,fashion |
| preference.maxMessagesPerWeek | String (255) | N | The maximum number of messages the user would like to receive in a given week. e.g. preference.maxMessagesPerWeek=3 |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/optout
HTTP Method(s): GET, POST
Pass in a program and phone number to initiate that program's opt-out flow.
Example
Request:
v=<version>
k=<key>
f=xml
phoneNumber=4151231234
programOwnerCode=PROG1
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<optOutResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1">
<infoMessage>
<key>optOutSuccessful<key>
<text>Opt-out successful<text>
</infoMessage>
</responseHeader>
</optOutResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| programOwnerCode | Code | Y | The code for the participating program. |
| externalId | String (255) | N | A client/external identifier code for the registered user. |
| phoneNumber | PhoneNumber | N | The mobile phone number of the opt-in user. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/offer
HTTP Method(s): GET, POST
Pass in a program and optional information such as offer status and location. Note that either phone number or external id must be included in the request. This will retrieve offers that best match the criteria.
Example
Request:
v=<version>
k=<key>
f=xml
programOwnerCode=PROG1
phoneNumber=4151231234
proximityCriteria.center.latitude=37.773831
proximityCriteria.center.longitude=-122.4235
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<offerGetResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
<offer>
<serialNumber>1100300005</serialNumber>
<name>Offer 1</name>
<contentType>
<code>TEXT</code>
<name>Text</name>
</contentType>
<header>offer header</header>
<bodyText>offer body text</bodyText>
<advertiser>
<code>ADV1</code>
<name>Adv1</name>
</advertiser>
<startDateTime>2010-11-25T00:00:00-10:00</startDateTime>
<endDateTime>2010-12-25T00:00:00-20:00</endDateTime>
<location>
<serialNumber>1100300005</serialNumber>
<code>1020_PLACECAST</code>
<name>1020 Placecast</name>
<geoLocation>
<address xsi:type="inputAddress" xmlns:xsi="http://www.w3...">
<addressType>
<code>STREET_ADDRESS</code>
<name>Street Address</name>
</addressType>
<countryCode>US</countryCode>
<address1>165 PAGE ST</address1>
<region1>SAN FRANCISCO</region1>
<region2>CA</region2>
<postalCode>94102</postalCode>
<neighborhood>HAYES VALLEY</neighborhood>
</address>
<geocode>
<latitude>37.773831</latitude>
<longitude>-122.4235</longitude>
</geocode>
</geoLocation>
<primaryPhoneNumber>+1 (415) 522 1020</primaryPhoneNumber>
</location>
</offer>
<listPager>
<listControl>
<startIndex>0</startIndex>
<segmentSize>10</segmentSize>
<segmentWindow>3</segmentWindow>
</listControl>
<startElement>1</startElement>
<endElement>1</endElement>
<currentSegment>1</currentSegment>
<previousSegments>0</previousSegments>
<nextSegments>0</nextSegments>
</listPager>
</offerGetResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| programOwnerCode | Code | Y | The code for the participating program. |
| externalId | String (255) | N | A client/external identifier code for the registered user. |
| phoneNumber | PhoneNumber | N | The mobile phone number of the opt-in user. |
| proximityCriteria | ProximityCriteria | N | The proximity criteria, which allows for searches around a specific latitutde and longitude. |
| statusCode | Code | N | The status filter for the offer. e.g. SENT, ACTIVATED, REDEEMED. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
| offer | List<Offer> | The offers matching the request. |
| listPager | ListPager | The standard list paging control. |
URL: http://<hostname>/geo/remote/rest/offer/activate
HTTP Method(s): GET, POST
Pass in a program, phone number and offer ID. This will activate/unlock the offer.
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| programOwnerCode | Code | Y | The code for the participating program. |
| externalId | String (255) | N | A client/external identifier code for the registered user. |
| phoneNumber | PhoneNumber | N | The mobile phone number of the opt-in user. |
| offerSerialNumber | Long | Y | The serial number of the offer. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/offer/redeem
HTTP Method(s): GET, POST
Pass in a program, phone number and offer ID. This will redeem the offer.
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| programOwnerCode | Code | Y | The code for the participating program. |
| externalId | String (255) | N | A client/external identifier code for the registered user. |
| phoneNumber | PhoneNumber | N | The mobile phone number of the opt-in user. |
| offerSerialNumber | Long | Y | The serial number of the offer. |
| transactionAmount | Measure | N | The transaction amount of the offer. |
| discountAmount | Measure | N | The discount amount of the offer. |
| redemptionDateTime | DateTime | N | The timestamp at which the offer was redeemed. |
| messageText | String | N | An optional message to send back to a subscriber, for example, that the offer redemption resulted in a statement credit. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/program
HTTP Method(s): GET, POST
Pass in a program name and/or date range. This will retrieve a list of programs that best match the criteria.
Example
Request:
v=<version>
k=<key>
f=xml
name=myProgram
startDateTime=2012-11-25T00:00:00Z
endDateTime=2012-12-25T00:00:00Z
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<programGetResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
<program>
<name>myProgram</name>
<advertiser>
<code>ADV1</code>
<name>Adv1</name>
</advertiser>
<startDate>2012-11-27T00:00:00Z</startDate>
<status>LIVE</status>
</program>
</programGetResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| name | Name | N | The name of the program. |
| startDateTime | DateTime | N | The start date of the program. |
| endDateTime | DateTime | N | The end date of the program. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
| program | List<Program> | The programs matching the request. |
URL: http://<hostname>/geo/remote/rest/program/modify
HTTP Method(s): POST
Create or update a program.
Example
Request:
v=<version>
k=<key>
f=xml
name=myProgram
advertiser.code=ADV1
advertiser.name=Adv1
startDateTime=2012-11-25T00:00:00Z
endDateTime=2012-12-25T00:00:00Z
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<programModifyResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
</programModifyResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| name | Name | Y | The name of the program to modify. |
| advertiser | BusinessEntity | Y | The advertiser for the program to modify. |
| startDateTime | DateTime | N | The start date of the program. |
| endDateTime | DateTime | N | The end date of the program. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/program/play
HTTP Method(s): GET, POST
Play a program.
Example
Request:
v=<version>
k=<key>
f=xml
name=myProgram
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<programPlayResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
</programPlayResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| name | Name | Y | The name of the program to play. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/program/pause
HTTP Method(s): GET, POST
Pause a program.
Example
Request:
v=<version>
k=<key>
f=xml
name=myProgram
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<programPauseResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
</programPauseResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| name | Name | Y | The name of the program to pause. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/program/cancel
HTTP Method(s): GET, POST
Cancel a program.
Example
Request:
v=<version>
k=<key>
f=xml
name=myProgram
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<programCancelResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
</programCancelResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| name | Name | Y | The name of the program to cancel. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/program/delete
HTTP Method(s): GET, POST
Delete a program.
Example
Request:
v=<version>
k=<key>
f=xml
name=myProgram
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<programDeleteResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
</programDeleteResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| name | Name | Y | The name of the program to delete. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/campaign
HTTP Method(s): GET, POST
Pass in a campaign name and/or date range. This will retrieve a list of programs that best match the criteria.
Example
Request:
v=<version>
k=<key>
f=xml
name=myCampaign
programName=myProgram
startDateTime=2012-11-25T00:00:00Z
endDateTime=2012-12-25T00:00:00Z
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<campaignGetResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
<campaign>
<name>myCampaign</name>
<programName>myProgram</programName>
<startDate>2012-11-27T00:00:00Z</startDate>
<endDate>2012-12-20T00:00:00Z</endDate>
<status>LIVE</status>
<advertiserBudget>
<quantity>1000.0</quantity>
<unitOfMeasureCode>USD</unitOfMeasureCode>
</advertiserBudget>
<advertiserRevenue>
<quantity>0.1</quantity>
<unitOfMeasureCode>USD</unitOfMeasureCode>
</advertiserRevenue>
<advertiserRevenueModel>
<code>DELIVERY</code>
<name>Delivery</name>
</advertiserRevenueModel>
<totalContentImpressionLimit xsi:nil="true"/>
<totalContentForwardLimit xsi:nil="true"/>
<totalContentConversionLimit xsi:nil="true"/>
<totalContentDeliveryLimit>10000</totalContentDeliveryLimit>
</campaign>
</campaignGetResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| name | Name | N | The name of the campaign. |
| programName | Name | Y | The name of the program the campaign belongs to. |
| startDateTime | DateTime | N | The start date of the campaign. |
| endDateTime | DateTime | N | The end date of the campaign. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
| campaign | List<Campaign> | The campaigns matching the request. |
URL: http://<hostname>/geo/remote/rest/campaign/modify
HTTP Method(s): POST
Create or update a campaign.
Example
Request:
v=<version>
k=<key>
f=xml
name=myCampaign
programName=myProgram
offer.serialNumber=1291335827
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<campaignModifyResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
</campaignModifyResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| name | Name | Y | The name of the campaign to modify. |
| programName | Name | Y | The name of the program this campaign belongs to. |
| offer | Content | Y | An offer to be tied to the campaign. |
| geofence | List<Geofence> | N | A list of geofences in which the campaign's offer is valid. |
| publisher | List<BusinessEntity> | N | A list of publishers for the campaign's offer. |
| startDateTime | DateTime | N | The start date of the campaign. |
| endDateTime | DateTime | N | The end date of the campaign. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/campaign/play
HTTP Method(s): GET, POST
Play a campaign.
Example
Request:
v=<version>
k=<key>
f=xml
name=myCampaign
programName=myProgram
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<campaignPlayResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
</campaignPlayResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| name | Name | Y | The name of the campaign to play. |
| programName | Name | Y | The name of the program this campaign belongs to. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/campaign/pause
HTTP Method(s): GET, POST
Pause a campaign.
Example
Request:
v=<version>
k=<key>
f=xml
name=myCampaign
programName=myProgram
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<campaignPauseResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
</campaignPauseResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| name | Name | Y | The name of the campaign to pause. |
| programName | Name | Y | The name of the program this campaign belongs to. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/campaign/cancel
HTTP Method(s): GET, POST
Cancel a campaign.
Example
Request:
v=<version>
k=<key>
f=xml
name=myCampaign
programName=myProgram
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<campaignCancelResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
</campaignCancelResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| name | Name | Y | The name of the campaign to cancel. |
| programName | Name | Y | The name of the program this campaign belongs to. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
URL: http://<hostname>/geo/remote/rest/campaign/delete
HTTP Method(s): GET, POST
Delete a campaign.
Example
Request:
v=<version>
k=<key>
f=xml
name=myCampaign
programName=myProgram
Response:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<campaignDeleteResponse xmlns="http://placecast.net/schema/geo">
<responseHeader requestId="1"/>
</campaignDeleteResponse>
Request
| Property | Type | Req'd | Description |
| requestHeader | RequestHeader | Y | The standard request header. |
| name | Name | Y | The name of the campaign to delete. |
| programName | Name | Y | The name of the program this campaign belongs to. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
