REST API

General API Information

Content Types

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.

Default Content Type

Except where noted, the default content type of all responses in the API is text/html.

Accepted Content Types

The content types currently understood by much of the API includes:

  • text/html
  • application/json

If a URI responds to a differing set of content types, that URI's definition includes the list of content types to which it responds.

Request Header

What is always accepted in the headers:

  • Referer
  • User-Agent
  • Accept
  • Content-Type

For specific URIs, other required or optional headers may be defined.

Response Header

What is commonly returned in the response headers:

  • Content-Type

For specific URI responses, other response headers may be defined.

Default Response

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.

API Key Use

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.

Authentication Requirements

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.

URIs

URI: /locations/search

The search URI should be used to find any locations available for your use.

GET

Request

Headers:

  • Accept: takes one of: application/json

Parameters:

  • q: The query string. A free-form query, it searches in the following ways (NOTE: blank queries return nothing):
    • by phone number in one of these forms: 10 sequential digits; with dash or period separators (ex: XXX-XXX-XXXX)
    • by zip code in one of these forms: 5 digit zip, 9 digit zip with dash (ex. 10001-4356)
    • by name of location
  • 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.
    • Format (date only): YYYY-MM-DD

    • Example:

      • ?updatedSince=2013-01-05
        • Format (date & time): YYYY-MM-DDTHH%3AMM%3ASS
        • Example:
      • ?updatedSince=2013-01-05T09%3A10%3A00

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
Response

The JSON response contains the following information:

  • A map of:
    • query: The original query line sent to the search engine
    • ok: 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 pages
    • time: 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.

URI: /locations/LOCATION

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

GET

Request

Headers:

  • Accept: takes one of: application/json
Response

Returns the set of information for the location as defined in Location Field Descriptions.

URI: /locations/LOCATION/menu

GET

Request

Headers:

  • Accept: takes: application/json
Response

application/json: For an application/json request, you get a JSON document that contains one of the following:

  1. A map containing:
    • location: A map containing the location information as defined in Location Field Descriptions
    • locationToMenus: A map of location-to-menus as defined in Location-to-Menu Map Field Descriptions
    • menus: A list of maps where each map contains a menu as defined in Menu Field Descriptions

URI: /locations/LOCATION/shortmenu

GET

Request

Headers:

  • Accept: takes: application/json
Response

application/json: For an application/json request, you get a JSON document that contains one of the following:

  1. A map containing:
    • type: The type of short menu.
    • numItems: The number of items in the short menu. Typically between 3 and 5, inclusive.
    • location: A map containing the location information as defined in Location Field Descriptions
    • shortmenu: A list of maps where each map contains a menu as defined in Short Menu Field Descriptions