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, DELETE
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. |
| 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. |
| locationReference | LocationReference | N | The location, if any, associated with this content. |
| radiusDistance | Measure | N | The geofence radius distance around the location 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, DELETE
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 phone number and location. 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>
<id>1</id>
<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. |
| offerId | Long | Y | The ID of the offer. |
Response
| Property | Type | Description |
| responseHeader | ResponseHeader | The standard response header. |
