API

Modify location

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.

Set new location

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.

Select candidate location

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.

Delete location

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.

Search location

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.

Match location

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.

Fetch content/creative

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.

Modify content/creative

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.

Delete content/creative

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.
contentSerialNumber Long Y The serial number of the content.

Response

Property Type Description
responseHeader ResponseHeader The standard response header.

Opt-in subscriber

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.

Opt-out subscriber

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.

Fetch offers

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.

Activate offer

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.

Redeem offer

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.

Fetch program

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.

Modify program

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.

Play program

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.

Pause program

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.

Cancel program

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.

Delete program

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.

Fetch campaign

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.

Modify campaign

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.

Play campaign

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.

Pause campaign

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.

Cancel campaign

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.

Delete campaign

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.