/Walls.io-API-Docs

Walls.io API Documentation

Clone with HTTPS

Use Git or checkout with SVN using the web URL.

Download ZIP
Find file
Switch branches/tags
Nothing to show
Latest commit 7e08660 Sep 20, 2017 @catearcher catearcher committed on GitHub Merge pull request #9 from DieSocialisten/pm-add-native-posts-creation 
Add info about the POST /posts endpoint
Permalink
Failed to load latest commit information.
FAQ.md text change Jul 28, 2014
README.md rename native post POST endpoint Sep 18, 2017

README.md

Walls.io API Documentation

Walls.io API

Contents

All endpoints require a valid API access token. Find out how to get one in the FAQs.

Note: It is not permitted to access our API directly from the browser, because this would expose your secret access token to the public. We are also rate limiting API calls, so calling the API from the browser will cause you to hit those rate limits very quickly.

Instead, call the API from your server and cache the posts there.

All endpoints, if called with a GET request, support the following response formats:

  • JSON: Expample request: api/posts.json
  • XML: Example request: api/posts.xml
  • RSS: Example request: api/posts.rss (This format is available on the posts-endpoint only!)

Posts Endpoints

Common Post fields

All responses from the /posts endpoints share the same set of fields:

  • id: The unique Walls.io ID of this post.
  • comment: The user-generated text content of this post.
  • type: The post type. Possible types are:
    • "twitter"
    • "facebook"
    • "instagram"
    • "googleplus"
    • "foursquare"
    • "youtube"
    • "flickr"
    • "appdotnet"
    • "tumblr"
    • "reddit"
    • "rss"
  • external_post_id: The post's id in the social network it originated from.
  • external_image: The user's profile pic.
  • external_name: The user's screen name or handle.
  • external_fullname: Some networks offer a "full name" or "display name" field in addition to the handle. This field contains this display name.
  • external_user_id: The user's ID in the social network.
  • post_image: The (user-generated) image that was added to this post. If there is also a post_video, the post_image is usually a preview image of the video.
  • post_video: The video that was added to this post.
  • permalink: The permalink of this post on the social network it was posted to.
  • post_link: Same as permalink.
  • twitter_entities: If the post type is twitter, this field contains an array of Twitter entities. For a discription of the Twitter entity format, see the Twitter API docs.
  • twitter_retweet: If the post type is twitter and the post is a retweet, this field contains true.
  • is_crosspost: If this post was posted to multiple social networks at the same time, all posts that came after the original one contain true for this field. The original post contains false.
  • is_highlighted: true if the post has been highlighted by a moderator; false otherwise.
  • status: Whether this post is active (visible) or inactive (invisible) on the Wall. Contains true if it is active.
  • created: The date and time when this post was created in the social network it was posted to. The timezone is UTC.
  • created_timestamp: Same as created, but as a UNIX timestamp.
  • modified: Ths date and time of the last modification of this Post object. This can be used to update existing posts, for example if their status was changed on Walls.io. The timezone is UTC.
  • modified_timestamp: Same as modified, but as a UNIX timestamp.
  • userlink: A link to the user's profile on the social network the post was posted to.
  • location: The name of the geographic position this post was created at, or null if none was set.
  • latitude: The latitude this post was created at, or null if the position was not set.
  • longitude: The longitude this post was created at, or null if the position was not set.

Media types

Walls.io posts have different media types and you can limit your search to these types using the media_types parameter. Valid media types are:

  • text: Posts that contain a comment, but no image or video.
  • image: Posts that contain a post_image, but no video. However, the comment field is still allowed in this media type.
  • video: Posts that contain a post_video. All other fields are also allowed in this media type, as long as it has a video.

GET api/posts.{format}

Returns a list of posts for a wall. The wall is determined by the access_token that must be passed with the request.

Note: This endpoint does not sort the posts by the date they were posted on their social networks, but in the order they arrive on the Walls.io server. Those sortings can differ greatly, especially after you add a new hashtag or other source in your wall settings.

This is done deliberately so you can never miss any "old" postings that arrive on this endpoint. However, this order of posts is usually not what you want to display in your frontend, so make sure to implement your own post sorting logic.

Example request

GET https://walls.io/api/posts.json?access_token=<YOUR_ACCESS_TOKEN>&fields=id,comment,type&limit=10&include_inactive=1

Parameters

  • access_token (required): Your Walls.io access token.
  • limit: The maximum number of posts you would like to receive. The maximum limit is 1000. If this parameter is not passed, the limit will be set to 50.
  • after: A post id used for pagination of results. You will only receive posts that have a higher ID than this.
  • before: A post id used for pagination of results. You will only receive posts that have a lower ID than this.
  • fields: A comma-separated list of fields you would like to receive for each post. For a full list of possible fields see the list of common fields.
  • types: A comma-separated list of the types of posts you would like to receive. For a full list of possible types see the type field in the list of common fields.
  • media_types: A comma-separated list of media types. Use this if you want to limit your query to text-only posts, or video posts, or image posts, or any combination of those. For a full list of media types see the media_type field in the list of media types.
  • highlighted_only: Set this to 1 if you would only like to receive posts that have been highlighted by a moderator.
  • include_inactive: Per default, only active posts are returned. If you want to receive all posts, regardless of status, set this to 1.

Example response

{
  "status":"success",
  "data":[
    {
      "id":"146670",
      "comment":"3 days and no #Starbucks \n\n#feinding",
      "type":"twitter",
      "external_image":"http:\/\/pbs.twimg.com\/profile_images\/471635099977408512\/cWPhJJWz_normal.jpeg",
      "external_name":"LOWERERWICK",
      "external_fullname":"Marko 9TOOTH",
      "external_user_id":"123456",
      "post_image":"",
      "post_link":"https:\/\/twitter.com\/LOWERERWICK\/status\/487213557436518400",
      "post_video":null,
      "twitter_entities":"{\"hashtags\":[{\"text\":\"Starbucks\",\"indices\":[14,24]},{\"text\":\"feinding\",\"indices\":[27,36]}],\"trends\":[],\"urls\":[],\"user_mentions\":[],\"symbols\":[]}",
      "twitter_retweet":false,
      "is_highlighted":false,
      "status":true,
      "created":"2014-07-10 14:35:38",
      "modified":"2014-07-10 14:35:39",
      "permalink":"https:\/\/twitter.com\/LOWERERWICK\/status\/487213557436518400",
      "userlink":"https:\/\/www.twitter.com\/LOWERERWICK",
      "location": "Knottingley",
      "latitude": "53.69547100000000",
      "longitude": "-1.25397500000000"
    },
    {
      "id":"146661",
      "comment":"According to #starbucks my name is #howard... #thatsnotmyname #starbucksfail",
      "type":"twitter",
      "external_image":"http:\/\/pbs.twimg.com\/profile_images\/378800000483014192\/cc7de90a32652e99b6716bda6e656481_normal.jpeg",
      "external_name":"TakeMe2TheRyan",
      "external_fullname":"Ryan Caruso",
      "external_user_id":"234567",
      "post_image":"",
      "post_link":"https:\/\/twitter.com\/TakeMe2TheRyan\/status\/487213383762989056",
      "post_video":null,
      "twitter_entities":"{\"hashtags\":[{\"text\":\"starbucks\",\"indices\":[13,23]},{\"text\":\"howard\",\"indices\":[35,42]},{\"text\":\"thatsnotmyname\",\"indices\":[46,61]},{\"text\":\"starbucksfail\",\"indices\":[62,76]}],\"trends\":[],\"urls\":[],\"user_mentions\":[],\"symbols\":[]}",
      "twitter_retweet":false,
      "is_highlighted":false,
      "status":true,
      "created":"2014-07-10 14:34:57",
      "modified":"2014-07-10 14:34:57",
      "permalink":"https:\/\/twitter.com\/TakeMe2TheRyan\/status\/487213383762989056",
      "userlink":"https:\/\/www.twitter.com\/TakeMe2TheRyan",
      "location": null,
      "latitude": null,
      "longitude": null
    }
  ]
}

GET api/posts/changed.{format}

Returns a list of posts for a wall, ordered by the time they were updated. The wall is determined by the access_token that must be passed with the request.

This endpoint should be used if you need to know about all updates to existing posts, as well as new posts. Every time an existing post is updated, it rises to the top of this endpoint's response.

Example request

GET https://walls.io/api/posts/changed.json?access_token=<YOUR_ACCESS_TOKEN>&since=1404996397

Parameters

  • access_token (required): Your Walls.io access token.
  • since (required): A timestamp used for pagination of results. You will only receive posts that have been updated since this date and time. Please use the current_time field of the response and pass it as the since field of the next request.
  • limit: The maximum number of posts you would like to receive. The maximum limit is 1000. If this parameter is not passed, the limit will be set to 50.
  • fields: A comma-separated list of fields you would like to receive for each post. For a full list of possible fields see the list of common fields.
  • types: A comma-separated list of the types of posts you would like to receive. For a full list of possible types see the type field in the list of common fields.
  • media_types: A comma-separated list of media types. Use this if you want to limit your query to text-only posts, or video posts, or image posts, or any combination of those. For a full list of media types see the media_type field in the list of media types.
  • highlighted_only: Set this to 1 if you would only like to receive posts that have been highlighted by a moderator.
  • include_inactive: Per default, only active posts are returned. If you want to receive all posts, regardless of status, set this to 1.

Example response

{
  "status":"success",
  "current_time":1408954107,
  "count":50,
  "data":[
    {
      "id": "17181205",
      "comment": "Oooh, it's a #Venti #Pike kinda day!! Can't even set the alarm \"later\" my internal clock is set.. That & my lovely roommates alarm blasting at 5:30 woke ME up (he's still sleeping).. lol. Bueno, laundry done, off to the gym before a meeting & getting the day started..",
      "external_fullname": null,
      "external_image": "http:\/\/images.ak.instagram.com\/profiles\/profile_372993670_75sq_1398301155.jpg",
      "external_name": "getfitgenes",
      "external_post_id": "769415235382107591_372993670",
      "external_user_id": "372993670",
      "is_crosspost": false,
      "is_highlighted": false,
      "permalink": "http:\/\/instagram.com\/p\/qtgxR9uV3H\/",
      "post_image": "http:\/\/scontent-a.cdninstagram.com\/hphotos-xfp1\/t51.2885-15\/10560907_307861969392635_1595149027_n.jpg",
      "post_link": "http:\/\/instagram.com\/p\/qtgxR9uV3H\/",
      "post_video":null,
      "status": true,
      "type": "instagram",
      "userlink": "http:\/\/instagram.com\/getfitgenes",
      "location": null,
      "latitude": "25.75100000000000",
      "longitude": "-80.23633333300000",
      "created": "2014-07-21 13:17:45",
      "modified": "2014-07-21 13:19:35"
    }
  ]
}

GET api/posts/{postId}.{format}

Returns a single post, specified by its Walls.io post id.

Example request

GET https://walls.io/api/posts/17824236.json?access_token=<YOUR_ACCESS_TOKEN>

Parameters

  • access_token (required): Your Walls.io access token.
  • fields: A comma-separated list of fields you would like to receive for each post. For a full list of possible fields see the list of common fields.

Example response

{
  "status": "success",
  "query": {
    "postId": 17181206
  },
  "current_time": 1408954568,
  "data": {
    "id": "17181206",
    "comment": "A heart on my cup and a wink! #ivepulled #guiltypleasure #starbucks",
    "type": "instagram",
    "external_image": "http:\/\/photos-f.ak.instagram.com\/hphotos-ak-xpf1\/10369543_654365497965469_839887771_a.jpg",
    "external_name": "mferrari1",
    "external_fullname": null,
    "external_user_id": "22059933",
    "post_image": "http:\/\/scontent-b.cdninstagram.com\/hphotos-xpa1\/t51.2885-15\/10499125_748994368486318_763693636_n.jpg",
    "post_link": "http:\/\/instagram.com\/p\/qtg9jrTRtz\/",
    "post_video":null,
    "twitter_entities": null,
    "twitter_retweet": false,
    "is_highlighted": false,
    "status": true,
    "location": null,
    "latitude": "51.48247833300000",
    "longitude": "-0.00957778300000",
    "created": "2014-07-21 13:19:25",
    "modified": "2014-07-21 13:19:35",
    "permalink": "http:\/\/instagram.com\/p\/qtg9jrTRtz\/",
    "userlink": "http:\/\/instagram.com\/mferrari1"
  }
}

POST api/posts.{format}

Adds a new Native Post to the Wall.

Native Posts can be posted to the Wall right away, or scheduled to be posted later. Please note that any images you add to your post have to be publicly accessible. It is not possible to update images via this API.

It is allowed to omit the text parameter if an image is added, and vice versa. It is not allowed to omit both fields at the same time. Same goes for user_name and user_image.

The response contains date strings in UTC and numeric UNIX timestamps in seconds.

Example request

curl -X POST \
  https://walls.io/api/posts.json \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'access_token=<YOUR_ACCESS_TOKEN>&text=Picture%20of%20a%20cat&image=https%3A%2F%2Furl.of.some%2Fother%2Fimage&user_name=Cat%20Facts&user_image=https%3A%2F%2Furl.of.some%2Fimage'

Parameters

  • text (required if image is omitted): Text content of the post.
  • image (required if text is omitted): Main image of the post.
  • user_name (required if user_image is omitted): Name of the user who created the post.
  • user_image (required if user_name is omitted): User image of the user who created the post.
  • link: The URL that a click on the posts timestamp or the image in the post detail view leads to.
  • location: Name of the location where this post was created, e.g. "Vienna, Austria". If no latlong data is added to the post then this location name is used to create geographic data via geocoding.
  • latitude: Latitude of the location where this post was created, as a float, e.g. 48.208
  • longitude: Longitude of the location where this post was created, as a float, e.g. 16.367
  • scheduled_timestamp: If set, the post is not added to the Wall's frontend right away but scheduled to be posted later. Must be a UNIX timestamp in seconds and must not be in the past.

Example response

{
  "status": "success",
  "info": [],
  "current_time": 1505470103,
  "data": {
    "image": "https://url.of.some/other/image",
    "text": "Picture of a cat",
    "user_image": "https://url.of.some/image",
    "user_name": "Cat Facts",
    "posted_at": "2017-09-15 10:08:23",
    "posted_timestamp": 1505470103
  }
}

GET api/analytics/posts.{format}

Returns the number of posts per social networks on your wall. Also returns the total number of posts.

Inactive posts (e.g. blacklisted posts or posts that were hidden via your wall moderation backend) are ignored.

Example request

GET https://walls.io/api/analytics/posts.json?access_token=<YOUR_ACCESS_TOKEN>

Parameters

  • access_token (required): Your Walls.io access token.
  • types: A comma-separated list of the types of posts you would like to receive. For a full list of possible types see the type field in the list of common fields.
  • since: Pass a UNIX timestamp to limit the result to posts that were posted after this time.
  • media_types: A comma-separated list of media types. Use this if you want to limit your query to text-only posts, or video posts, or image posts, or any combination of those. For a full list of media types see the media_type field in the list of media types.
  • highlighted_only: Set this to 1 if you would only like to receive posts that have been highlighted by a moderator.
  • include_inactive: Per default, only active posts are returned. If you want to receive all posts, regardless of status, set this to 1.

Example response

{
  "status": "success",
  "data": {
    "twitter": 463,
    "instagram": 395,
    "flickr": 125,
    "facebook": 83,
    "youtube": 72,
    "googleplus": 60,
    "total": 1198
  }
}

GET api/analytics/users.{format}

Returns the number of unique users that have posted on your wall, grouped by social network. Also returns the total number of unique users.

Users who only have inactive posts (e.g. blacklisted posts or posts that were hidden via your wall moderation backend) on your wall are ignored.

Example request

GET https://walls.io/api/analytics/users.json?access_token=<YOUR_ACCESS_TOKEN>

Parameters

  • access_token (required): Your Walls.io access token.
  • types: A comma-separated list of the types of posts you would like to receive. For a full list of possible types see the type field in the list of common fields.
  • since: Pass a UNIX timestamp to limit the result to posts that were posted after this time.
  • media_types: A comma-separated list of media types. Use this if you want to limit your query to text-only posts, or video posts, or image posts, or any combination of those. For a full list of media types see the media_type field in the list of media types.
  • highlighted_only: Set this to 1 if you would only like to receive posts that have been highlighted by a moderator.
  • include_inactive: Per default, only active posts are returned. If you want to receive all posts, regardless of status, set this to 1.

Example response

{
  "status": "success",
  "data": {
    "twitter": 425,
    "instagram": 386,
    "facebook": 83,
    "youtube": 49,
    "googleplus": 35,
    "flickr": 24,
    "total": 1002
  }
}

GET api/ads.{format}

Returns a list of ads for a wall. Ads are uploaded and managed in the Walls.io settings. The Wall is determined by the access_token that must be passed with the request.

Example request

GET https://walls.io/api/ads.json?access_token=<YOUR_ACCESS_TOKEN>

Parameters

  • access_token (required): Your Walls.io access token.

Example response

{
    "status": "success",
    "data": [
        {
            "id": "5767ed0e-290c-4926-ad42-042cac1facad",
            "image": "https:\/\/walls.io\/link\/to\/image.jpg",
            "imageAspectRatio": 1.6,
            "link": "https:\/\/www.facebook.com"
        }
    ]
}