List posts

GET

/posts

posts

NOTE: When paging through the posts returned by this endpoint, there will be at most 1,000 posts that can be returned (eg. 50 pages worth of posts with the default per_page value of 20). In areas where there are more than 1,000 posts, clients can use more specific query parameters to adjust which posts are returned.
NOTE: Passing the latitude, longitude and radius parameters filters all posts by their location and so these parameters will temporarily override the current users' location preferences. When latitude, longitude and radius are not specified, public posts will be filtered by the current users' location preferences.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request GET 'https://trashnothing.com/api/v1.2/posts?types=&sources='

Response Example

200 - Example 1

{
    "end_index": 0,
    "group_ids": [
        "string"
    ],
    "last_listings_view": "2019-08-24T14:15:22Z",
    "num_pages": 0,
    "num_posts": 0,
    "page": 0,
    "per_page": 0,
    "posts": [
        {
            "content": "This ultrasonic diffuser creates an aroma in your home. It comes with two essential oils - mint and lavender.",
            "date": "2018-02-05T15:10:21",
            "footer": null,
            "group_id": 6,
            "latitude": 43.653226,
            "longitude": -79.383184,
            "outcome": "satisfied",
            "photos": [
                {
                    "images": [
                        {
                            "height": 120,
                            "url": "https://trashnothing.com/img/2018-02-05/cfsbfm-39051735845_379baab73f.90x120.jpg",
                            "width": 90
                        },
                        {
                            "height": 240,
                            "url": "https://trashnothing.com/img/2018-02-05/cfsbfm-39051735845_379baab73f.180x240.jpg",
                            "width": 180
                        },
                        {
                            "height": 360,
                            "url": "https://trashnothing.com/img/2018-02-05/cfsbfm-39051735845_379baab73f.270x360.jpg",
                            "width": 270
                        },
                        {
                            "height": 500,
                            "url": "https://trashnothing.com/img/2018-02-05/cfsbfm-39051735845_379baab73f.375x500.jpg",
                            "width": 375
                        }
                    ],
                    "photo_id": "695624-768616",
                    "thumbnail": "https://trashnothing.com/img/2018-02-05/cfsbfm-39051735845_379baab73f.90x120.jpg",
                    "url": "https://trashnothing.com/img/2018-02-05/cfsbfm-39051735845_379baab73f.375x500.jpg"
                }
            ],
            "post_id": 3171898,
            "title": "Ultrasonic diffuser (Downtown Toronto)",
            "type": "offer",
            "user_id": 2933
        }
    ],
    "start_index": 0
}

Request

Query Params

sort_by

string

optional

How to sort the posts that are returned. One of: date, active, distance

Date sorting will sort posts from newest to oldest. Active sorting will sort active posts before satisfied, withdrawn and expired posts and then sort by date. Distance sorting will sort the closest posts first.

types

string

required

A comma separated list of the post types to return. The available post types are: offer, taken, wanted, received, admin

sources

string

required

A comma separated list of the post sources to retrieve posts from. The available sources are: groups, trashnothing, open_archive_groups. The trashnothing source is for public posts that are posted on trash nothing but are not associated with any group. The open_archive_groups source provides a way to easily request posts from groups that have open_archives set to true without having to pass a group_ids parameter. When passed, it will automatically return posts from open archive groups that are within the area specified by the latitude, longitude and radius parameters (or the current users' location if latitude, longitude and radius aren't passed).

NOTE: For requests using an api key instead of oauth, passing the trashnothing source or the open_archive_groups source makes the latitude, longitude and radius parameters required.

group_ids

string

optional

A comma separated list of the group IDs to retrieve posts from. This parameter is only used if the 'groups' source is passed in the sources parameter and only groups that the current user is a member of or that are open archives groups will be used (the group IDs of other groups will be silently discarded*).

NOTE: For requests using an api key instead of oauth, this field is required if the 'groups' source is passed. In addition, only posts from groups that have open_archives set to true will be used (the group IDS of other groups will be silently discarded*).

*To determine which group IDs were used and which were discarded, use the group_ids field in the response.

per_page

integer

optional

The number of posts to return per page (must be >= 1 and <= 100).

page

integer

optional

The page of posts to return.

device_pixel_ratio

number

optional

Client device pixel ratio used to determine thumbnail size (default 1.0).

latitude

number

optional

The latitude of a point around which to return posts.

longitude

number

optional

The longitude of a point around which to return posts.

radius

number

optional

The radius in meters of a circle centered at the point defined by the latitude and longitude parameters. When latitude, longitude and radius are passed, only posts within the circle defined by these parameters will be returned.

date_min

string

optional

Only posts newer than or equal to this UTC date and time will be returned. If unset, defaults to the current date and time minus 90 days.

date_max

string

optional

Only posts older than this UTC date and time will be returned. If unset, defaults to the current date and time.

outcomes

string

optional

A comma separated list of the post outcomes to return. The available post outcomes are: satisfied, withdrawn

There are also a couple special values that can be passed. If set to an empty string (the default), only posts that are not satisfied and not withdrawn and not expired are returned. If set to 'all', all posts will be returned no matter what outcome the posts have.

user_state

string

optional

If user_state is set, only posts matching the state specified will be returned. Only one state may be passed and it must be one of the following: viewed, replied, bookmarked

NOTE: This option will only work with oauth requests.

Responses

🟢200The posts and paging data.

application/json

Body

end_index

integer

optional

The index of the last post being returned (an integer between start_index and num_posts).

group_ids

array[string]

optional

The IDs of the groups that the posts were retrieved from (will be null when no group IDs were used). These IDs may be a subset of the requested group IDs when a request includes group IDs for groups that are not open archives and that the current user is not a member of. If the open_archive_groups source is used, these IDs may include the IDs of open archive groups that weren't present in the group_ids parameter of the request.

last_listings_view

string <date-time>

optional

The UTC date and time when the current user last viewed the newest posts on the All Posts page (may be null).

NOTE: For this to be accurate, clients must update the last_listings_view property of the current user every time the user is shown the newest posts on the All Posts page.

NOTE: For requests using an api key instead of oauth, this field is always null.

num_pages

integer

optional

The total number of pages available.

num_posts

integer

optional

The total number of posts available.

page

integer

optional

The page number of the posts being returned.

per_page

integer

optional

The number of posts being returned per page.

posts

array[object (Post) {15}]

optional

content

string

optional

date

string <date-time>

optional

The UTC date and time when the post was published.

expiration

string <date-time>

optional

The UTC date and time when the post will expire. Currently only offer and wanted posts expire. For all other posts, expiration is always null.

footer

string

optional

Some groups add footers to posts that are separate and sometimes unrelated to the post itself - such as reminders about group rules or features (may be null).

group_id

string

optional

The group ID of the post. For public posts, this is always null.

latitude

number

optional

May be null if a post hasn't been mapped.

longitude

number

optional

May be null if a post hasn't been mapped.

outcome

string

optional

For offer and wanted posts, this indicates the outcome of the post which is null if no outcome has been set yet.

Offer post outcomes will be one of: satisfied, withdrawn, promised, expired

Wanted post outcomes will be one of: satisfied, withdrawn, expired

For all other posts, outcome is always null.

photos

array[object (Photo) {5}]

optional

Details about the photos associated with this post (may be null if there are no photos).

post_id

string

optional

source

string

optional

The source of the post. One of: groups, trashnothing, open_archive_groups. A value of groups or open_archive_groups indicates the post is from a group and the group_id field will contain the ID of the group. A value of trashnothing indicates the post is a public post not associated with any group.

title

string

optional

type

string

optional

The type of post. One of: offer, taken, wanted, received, admin

url

string

optional

The link to use to view the post on the trash nothing site.

user_id

string

optional

start_index

integer

optional

The index of the first post being returned (an integer between 1 and num_posts).

🟠400Missing or invalid parameters.

Modified at 2022-09-11 18:59:48

Rotate a photo

Submit a post