This documentation is obsolete. Please see updated documentation at http://docs.singleplatform.com/spv2/rest-api/ |
The SinglePlatform REST API is a well-behaving API that returns results according to the requested content type. Use the Accept header in a request to indicate you want the result in a specific format.
Except where noted, the default content type of all responses in the API is text/html.
The content types currently understood by much of the API includes:
text/htmlapplication/jsonIf a URI responds to a differing set of content types, that URI's definition includes the list of content types to which it responds.
What is always accepted in the headers:
For specific URIs, other required or optional headers may be defined.
What is commonly returned in the response headers:
For specific URI responses, other response headers may be defined.
Unless otherwise noted, the default response from an action is a text/html document with the following fields:
code: Matches the HTTP response code.status: The Message associated with the HTTP response code.ok: Either "true" or "false", if the HTTP response code is in the 2xx family.To receive a document in another format, that format must be specified in the Content-Type request header.
Unless otherwise noted, all API requests for HTML data should be accompanied by your API Key.
For details about what is the API Key and how you can obtain it, see: API Key.
Unless otherwise noted, all API requests for JSON data require the request to be authenticated using your Client ID and Signing Key.
For details about how to acquire and use them, see API Authentication.
The search URI should be used to find any locations available for your use.
Headers:
Accept: takes one of: application/jsonParameters:
q: The query string. A free-form query, it searches in the following ways (NOTE: blank queries return nothing):page: The page number. A zero-based value. The default value is 0 for the first page.count: The number of results per page. The default value is 20, and the maximum value is 1000.updatedSince: Filter the results to list only those locations updated since the specified date and time.URI Examples:
The following two example URIs are equivalent and return the first 20 of the available locations as the 0th page of locations.
/locations/search /locations/search?q=&page=0&count=20 |
An example query URL that returns the third page of results for all locations with Haru in the name:
/locations/search?q=Haru&page=3&count=100 |
The following example returns the first 20 of the locations updated since January 18, 2013 at 2:03 pm as the 0th page of locations.
/locations/search?updatedSince=2013-01-18T14%3A03%3A00 |
The JSON response contains the following information:
query: The original query line sent to the search engineok: true if the search was a success. false if the search was not a success. If the search was a success but no results were found, this value is true.page: Which page these results are on, should match the original query (or be 0 if not defined in the original query)count: Number of results per page, should match the original query (or be 20 if not defined in the original query)total: The full number of results that the search have matched; can be used to calculate total number of pagestime: The date/time when the query was performed in Eastern Standard Time (EST).results: A list of maps, each is a location with the keys as defined in Location Field Descriptions.In the URI, LOCATION should be replaced by the ID of the location. For example, the ID for Haru might be haru-7 and the URI would be /locations/haru-7
Headers:
Accept: takes one of: application/jsonReturns the set of information for the location as defined in Location Field Descriptions.