Need Help? Support

API Overview

Data endpoints are depricated and will be disabled on August 5. (read more)

Developers should implement Singly Health Data Fabic, a fault-tolerant, schedulable system that pushes unified data from any apps or devices your users have authenticated, directly to your database.

Request access to Health Data Fabric

We are committed to make the transition smooth for current users, so if this will be an issue for you, please don't hesitate to contact us.

Profiles

The first time a service is authorized for an app, an account is created, and any additional services then authorized are all attached to the same account and access token. Each service is called a profile, and all the profiles authorized are available under /profiles, see the Profiles Documentation.

Services

The service endpoints each return an object containing data synched from that service. See the full Services Documentation.

Items of a certain type

The types endpoints return objects representing a single type of data, like a photo or a contact. See the full Types Documentation.

Common Query Parameters

  • limit the number of results to return (defaults to 20, unlimited max).
  • since The unix timestamp (in epoch milliseconds) of the oldest entry. Defaults to 0, useful when looking for newer things since the last request.
  • until The unix timestamp (in epoch milliseconds) of the newest entry. Defaults to now. Use this to page back in time, passing in the oldest timestamp of the previous results.

Full Text Search

Any call to /types/* or /services/* can take a query parameter q, which will return results that match a full text search on the following fields:

  • Name, handle/nickname, and email for contacts
  • Text in statuses
  • Title and url in news links
  • Title and description for photos

Participants Filtering

Any call to /types/* or /services/* can take a query parameter participants which filters the result set to include the given comma-delimited user ids as all having participated in some way with the source entry. Participants include the authors and anyone commenting or liking the entry on the given service, only the first 16 participants are indexed. There is some additional special syntax to make it easier:

  • self is used instead to refer to the profile owner's own id on the service
  • ^id the carat '^' can be prefixed to any id to require that participant to be the author of the entry
  • >number a minimum number of total participants can be required, from 1 to 16

Services that have participants indexed are currently Facebook posts (wall and feed), Tweets (of any kind), Instagram photos, foursquare checkins, and tumblr posts. If you need more than those just ask!

Example request:

GET /services/facebook/home?participants=self,^132452421,>5&within=10&access_token=my_token

This would return any entries authored by 132452421 that I've either liked or commented on and has at least three other participants.

Geo/Location Filtering

By adding two query parameters to any /types/* or /services/* calls the results will be filtered to just ones that have location information (checkins, tweets, photos, etc) and are within the specified distance in kilometers of the given latitude,longitude:

Example request:

GET /types/all_feed?near=37.76,-122.41&within=10&access_token=my_token

Example response:

Global Items

Every item has a system-wide unique id that it can be retrieved by:

GET /id/:id

Example request:

GET /id/7c0567337c6031ef17d9e43feb05817a?access_token=my_token

Example response:

The original IDR can also be URL-encoded and given instead:

GET /id/tweet%3A1704421%40twitter%2Ftimeline%191347905821540352?access_token=my_token

Example response:

The map Parameter

This parameter is experimental and likely to change.

Including map=true in a request will add an extra field to each item in the JSON response containing normalized data. For example, if three different services provide

  • first_name / last_name
  • full_name
  • fullName

asking for map will make all of these accessible at item.map.name.

It's easiest to use the API Explorer in the /services/* area on live data to see what values are available. If your app has custom needs for normalization, just ask, new ones are added all the time!

Field selection

Because you probably don't need everything returned by a service or type, you can save time and bandwidth by selecting the only the set of fields you use. Simply include a fields parameter with a comma separated list of JSON-style paths to the data you want.

The endpoints will intelligently handle access into both objects and arrays, as well as dynamic data like that included by the map parameter. If a path doesn't exist in the original object, it appears as null.

Example request:

GET
/types/photos?access_token=my_token&fields=data.images.source,data.images.width,data.images.height

Example response:

Proxy to Service API

You can make calls directly to any supported service API both to fetch any data not currently supported and importantly to post or modify items on the service (tweet something, like something, upload a pic, etc). See the full Proxy Documentation.

By ID

It's common to need to get an entry from a specific service and endpoint from just the ID, such as a friend who commented on an entry, to fetch the full information for them. As long as the data has been synced, it can be retrieved by the native service ID:

GET /services/:service/:endpoint/:id

Example request:

GET https://api.singly.com/services/twitter/friends/1704421?access_token=my_singly_token

Example response:

Errors

Error responses will be returned as JSON with an HTTP status code in the 400 or 500 range. The JSON will always be of the format

{
  "error": "Something went wrong."
}

In the future, a numeric code may be included for easy comparisons. Extra data may also be attached, like debug information or references to documentation.