@datafire/trashnothing v3.0.0

@datafire/trashnothing

Client library for trash nothing

Installation and Usage

npm install --save @datafire/trashnothing

let trashnothing = require('@datafire/trashnothing').create({
  api_key: "",
  access_token: "",
  refresh_token: "",
  client_id: "",
  client_secret: "",
  redirect_uri: ""
});

.then(data => {
  console.log(data);
});

Description

This is the REST API for trashnothing.com.

To learn more about the API or to register your app for use with the API visit the trash nothing Developer page.

NOTE: All date-time values are UTC and are in ISO 8601 format (eg. 2019-02-03T01:23:53).

Actions

oauthCallback

Exchange the code passed to your redirect URI for an access_token

trashnothing.oauthCallback({
  "code": ""
}, context)

Input

• input object
  • code required string

Output

• output object
  • access_token string
  • refresh_token string
  • token_type string
  • scope string
  • expiration string

oauthRefresh

Exchange a refresh_token for an access_token

trashnothing.oauthRefresh(null, context)

Input

This action has no parameters

Output

• output object
  • access_token string
  • refresh_token string
  • token_type string
  • scope string
  • expiration string

get_conversations

List conversations

trashnothing.get_conversations({}, context)

Input

• input object
  • category string: Used to filter messases by category. Must be set to one of the following three categories: inbox, archived, blocked
  • page integer: The page of conversations to return.
  • per_page integer: The number of conversations to return per page (must be >= 1 and <= 30).
  • num_messages integer: The number of recent messages to return with each conversation. Additional messages can be retrieved using get conversation messages endpoint.
  • include_num_unread integer: If set to 1, the num_unread field in the response will be set to the count of the total number of conversations that have unread messages. This is useful for showing users the total number of unread messages that they have in their inbox. Calculating the count will slow the request down a bit so setting this should be avoided for requests where it's not needed (eg. requesting archived or blocked conversations or requests that are just paging through older conversations).
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).

Output

• output object
  • conversations array
    • items Conversation
  • num_unread integer: If the include_num_unread parameter is set to 1, this will be set to the total number of conversations that have unread messages matching the query parameters of the request. If the include_num_unread parameter is set to 0, this will be null.
  • page integer
  • per_page integer

mark_all_conversations_read

Mark all conversations as read

trashnothing.mark_all_conversations_read({
  "message_id": ""
}, context)

Input

• input object
  • message_id required string: The message_id of the most recent message from the conversations that the client has downloaded.

Output

Output schema unknown

search_conversations

Searches all conversations except blocked conversations.

trashnothing.search_conversations({
  "search": ""
}, context)

Input

• input object
  • search required string: The search query used to find conversations and messages.
  • page integer: The page of conversations to return.
  • per_page integer: The number of conversations to return per page (must be >= 1 and <= 30).
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).

Output

• output object
  • conversations array
    • items Conversation
  • page integer
  • per_page integer
  • search string

delete_conversation

Delete conversation

trashnothing.delete_conversation({
  "conversation_id": "",
  "message_id": ""
}, context)

Input

• input object
  • conversation_id required string: The ID of the conversation to delete.
  • message_id required string: The ID of the newest message in the conversation that the client has downloaded.

Output

Output schema unknown

archive_conversation

Archive conversation

trashnothing.archive_conversation({
  "conversation_id": ""
}, context)

Input

• input object
  • conversation_id required string: The ID of the conversation to archive.

Output

Output schema unknown

block_conversation

Block conversation

trashnothing.block_conversation({
  "conversation_id": ""
}, context)

Input

• input object
  • conversation_id required string: The ID of the conversation to block.

Output

Output schema unknown

mark_conversation_read

Mark conversation as read

trashnothing.mark_conversation_read({
  "conversation_id": "",
  "message_id": ""
}, context)

Input

• input object
  • conversation_id required string: The ID of the conversation to mark as read.
  • message_id required string: The ID of the newest message in the conversation that the current user has read.

Output

Output schema unknown

get_conversation_messages

List conversation messages

trashnothing.get_conversation_messages({
  "conversation_id": ""
}, context)

Input

• input object
  • conversation_id required string: The ID of the conversation to return messages from.
  • page integer: The page of messages to return.
  • per_page integer: The number of messages to return per page (must be >= 1 and <= 30).
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).
  • include_conversation integer: If set to 1, the conversation will be returned along with the messages.

Output

• output object
  • conversation Conversation
  • messages array
    • items Message
  • page integer
  • per_page integer

reply_to_conversation

Reply to conversation

trashnothing.reply_to_conversation({
  "conversation_id": "",
  "content": ""
}, context)

Input

• input object
  • conversation_id required string: The ID of the conversation to reply to.
  • content required string: The content of the reply.
  • photo_ids string: A comma separated list of the IDs of the photos that should be attached to this message.
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).

Output

• output Message

report_conversation

Report conversation

trashnothing.report_conversation({
  "conversation_id": "",
  "reason": ""
}, context)

Input

• input object
  • conversation_id required string: The ID of the conversation to report.
  • reason required string: A user provided reason why the conversation is being reported.

Output

Output schema unknown

unarchive_conversation

Unarchive conversation

trashnothing.unarchive_conversation({
  "conversation_id": ""
}, context)

Input

• input object
  • conversation_id required string: The ID of the conversation to unarchive.

Output

Output schema unknown

unblock_conversation

Unblock conversation

trashnothing.unblock_conversation({
  "conversation_id": ""
}, context)

Input

• input object
  • conversation_id required string: The ID of the conversation to unblock.

Output

Output schema unknown

send_feedback

Allows users to send feedback about the trashnothing.com site or apps.

trashnothing.send_feedback({
  "subject": "",
  "message": ""
}, context)

Input

• input object
  • subject required string: The subject.
  • message required string: The message.
  • meta string: Extra information set by the client that may be useful to contextualize the feedback (eg. operating system details, browser details, app details, device details).

Output

Output schema unknown

search_groups

Search groups

trashnothing.search_groups({}, context)

Input

• input object
  • name string: Find groups that have the given text somewhere in their name (case insensitive).
  • latitude number: Find groups near the given latitude and longitude.
  • longitude number: Find groups near the given latitude and longitude.
  • distance number: When latitude and longitude are passed, distance can optionally be passed to only return groups within a certain distance (in kilometers) from the point specified by the latitude and longitude. The distance must be > 0 and <= 150 and will default to 100.
  • country string: Find groups in the given country where country is a 2 letter country code for the country (see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 ).
  • region string: For countries with regions (AU, CA, GB, US), search groups in a specific region as specified by the region abbreviation. The supported regions and their abbreviations are listed below. NOTE: The region and postal_code parameters cannot be used at the same time and if both are passed then the postal_code will take priority. --- AU - QLD: Queensland - SA: South Australia - TAS: Tasmania - VIC: Victoria - WA: Western Australia - NT: Northern Territory - NSW: New South Wales - ACT CA - AB: Alberta - BC: British Columbia - MB: Manitoba - NB: New Brunswick - NL: Newfoundland and Labrador - NS: Nova Scotia - ON: Ontario - QC: Quebec - SK: Saskatchewan - PE: Prince Edward Island GB - E: East - EM: East Midlands - LDN: London - NE: North East - NW: North West - NI: Northern Ireland - SC: Scotland - SE: South East - SW: South West - WA: Wales - WM: West Midlands - YH: Yorkshire and the Humber US All 50 states and the District of Columbia are supported. For the abbreviations, see: https://github.com/jasonong/List-of-US-States/blob/master/states.csv
  • postal_code string: Find groups in the given postal code. Only a few countries support postal code searches (US, CA, AU, GB). The country parameter must be passed when the postal_code parameter is set. NOTE: The region and postal_code parameters cannot be used at the same time and if both are passed then the postal_code will take priority.
  • page integer: The page of groups to return.
  • per_page integer: The number of groups to return per page (must be >= 1 and <= 100).

Output

• output object
  • end_index integer: The index of the last group being returned (an integer between start_index and num_groups).
  • groups array
    • items Group
  • num_groups integer: The total number of groups available.
  • num_pages integer: The total number of pages available.
  • page integer: The page number of the groups being returned.
  • per_page integer: The number of groups being returned per page.
  • start_index integer: The index of the first group being returned (an integer between 1 and num_groups).

get_groups_by_ids

Retrieve multiple groups

trashnothing.get_groups_by_ids({
  "group_ids": ""
}, context)

Input

• input object
  • group_ids required string: The IDs of the groups to retrieve. If more than 20 group IDs are passed, only the first 20 groups will be returned.

Output

• output array
  • items Group

join_groups

Request membership to one or more groups. NOTE: Any group with a has_questions field set to true will also require answers to the groups' new member questionnaire to be submitted. Groups waiting for answers will have their membership field set to 'pending-questions'. And the questionnaire that needs to be answered can be found in the membership.questionnaire field of the group after a subscribe request is made to that group.

trashnothing.join_groups({
  "group_ids": ""
}, context)

Input

• input object
  • group_ids required string: A comma separated list of the IDs of the groups to join.

Output

• output object
  • groups array: Updated data about the groups and the current users' membership to each group.
    • items Group
  • over_group_limit boolean: When this is true, it means that some of the membership requests weren't processed in order to keep the user from going over the 12 group limit (the membership field of the groups can be used to determine which requests were processed).

get_group

Retrieve a group

trashnothing.get_group({
  "group_id": ""
}, context)

Input

• input object
  • group_id required string: The ID of the group to retrieve.

Output

• output Group

submit_answers

Submits answers to a groups' membership questionnaire. The request body should be a JSON object mapping each question from the group membership.questionnaire.questions field to an answer (eg. {"Where do you live?": "New York City"} ). All questions are required so no null or empty string answers are allowed.

trashnothing.submit_answers({
  "group_id": "",
  "body": {}
}, context)

Input

• input object
  • group_id required string: The group ID of the group that the user is submitting answers for.
  • body required object

Output

• output Group

contact_moderators

Contact group moderators

trashnothing.contact_moderators({
  "group_id": "",
  "subject": "",
  "message": ""
}, context)

Input

• input object
  • group_id required string: The group ID of the group whose moderators will be contacted.
  • subject required string: The subject of the message.
  • message required string: The body of the message.

Output

Output schema unknown

leave_group

Leave a group

trashnothing.leave_group({
  "group_id": ""
}, context)

Input

• input object
  • group_id required string: The ID of the group to leave.

Output

• output Group

upload_photo

Create a photo

trashnothing.upload_photo({
  "photo": ""
}, context)

Input

• input object
  • photo required string, object: Photo to upload.
    • content string
    • encoding string (values: ascii, utf8, utf16le, base64, binary, hex)
    • contentType string
    • filename string
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).

Output

• output PhotoResult

get_photos_by_ids

Retrieve multiple photos

trashnothing.get_photos_by_ids({
  "photo_ids": ""
}, context)

Input

• input object
  • photo_ids required string: The IDs of the photos to retrieve. If more than 50 photo IDs are passed, only the first 50 photos will be returned.
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).

Output

• output array
  • items PhotoResult

delete_photo

Delete a photo

trashnothing.delete_photo({
  "photo_id": ""
}, context)

Input

• input object
  • photo_id required string

Output

Output schema unknown

rotate_photo

Rotate a photo

trashnothing.rotate_photo({
  "photo_id": "",
  "degrees": 0
}, context)

Input

• input object
  • photo_id required string
  • degrees required integer: Rotation in degrees - currently only 90, 180 and 270 are supported which correspond to rotate left, rotate upside down and rotate right.
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).

Output

• output PhotoResult

get_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.

trashnothing.get_posts({
  "types": "",
  "sources": ""
}, context)

Input

• input object
  • types required string: A comma separated list of the post types to return. The available post types are: offer, taken, wanted, received, admin
  • sources required string: 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: 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: The number of posts to return per page (must be >= 1 and <= 100).
  • page integer: The page of posts to return.
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).
  • latitude number: The latitude of a point around which to return posts.
  • longitude number: The longitude of a point around which to return posts.
  • radius number: 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: 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: Only posts older than this UTC date and time will be returned. If unset, defaults to the current date and time.
  • outcomes string: 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 are returned. If set to 'all', all posts will be returned no matter what outcome the posts have.
  • user_state string: 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.

Output

• output object
  • end_index integer: The index of the last post being returned (an integer between start_index and num_posts).
  • group_ids array: 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.
    • items string
  • last_listings_view string: 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: The total number of pages available.
  • num_posts integer: The total number of posts available.
  • page integer: The page number of the posts being returned.
  • per_page integer: The number of posts being returned per page.
  • posts array
    • items Post
  • start_index integer: The index of the first post being returned (an integer between 1 and num_posts).

submit_post

Submits a new post. NOTE: An alternate way to submit posts that does quicker client side validation is to use the script served by the API at the /posts/client.js endpoint (see the description of the /posts/client.js endpoint for usage instructions).

trashnothing.submit_post({
  "type": "",
  "title": "",
  "location": "",
  "session": ""
}, context)

Input

• input object
  • group_ids string: A comma separated list of group IDs to submit the post to (if any).
  • type required string: The type of post. One of: offer, wanted
  • title required string: A short description of the item(s).
  • location required string: A short location description.
  • content string: A longer description of the item(s).
  • fair_offer integer: If set to 1, the post will be posted with the Fair Offer Policy (only valid for offer posts - see https://trashnothing.com/fair_offer_policy ).
  • latitude number: The latitude corresponding to the location description provided. If latitude and longitude are not provided, an attempt will be made to automatically geocode the location. If the location is unable to be geocoded, the post will be rejected and will have to be resubmitted with a latitude and longitude corresponding to the location or resubmitted with a different location that can be automatically geocoded. NOTE: The latitude and longitude should NOT be the users' exact location because we don't want to publicize their exact location unless their location description is their full address (which is not recommended). When a post is rejected because it can't be geocoded, the returned error will have its identifier property set to 'unknown-location'.
  • longitude number: The longitude corresponding to the location description provided. (see the NOTE in latitude description)
  • photo_ids string: A comma separated list of the IDs of the photos that should be attached to this post.
  • session required string: A JSON string representing a temporary object that is used to store data about the submission process for a single post. The first time a post is submitted, session should be a new empty object (eg. '{}'). The session object should be persisted by the client until that post is successfully submitted and then it can be discarded so that the next post will start over with a new empty session object. Every time a post is submitted and the response indicates that the submission was not successful, the session object returned in the response should override the clients copy of the session.
  • preferences string: A JSON string representing a permanent object that the client persists and modifies based on warnings returned by the post submission process and user input. Some warnings returned after submitting a post have a preference_key string property so that users can opt out of those warnings in the future. To save this opt-out preference, set the property indicated by the preference_key in the preferences object (eg. preferencespreference_key = 1). The preferences object is never modified by the server - it is up to the client to initialize, modify and persist the preferences object.

Output

• output object
  • identifier string: When an error or warning is returned, this will contain a short string representing the type of error or warning that occurred. Is null on success.
  • message string: Contains text describing the reason a post was not successful. Is null on success.
  • preference_key string: Certain types of warnings can be opted out of. These warnings will set preference_key to a string that can be set in the preferences object by the client to opt out of that type of warning in the future (see the description of the preferences parameter for more details). Is null for errors, success and warnings that can't be opted out of.
  • result string: One of: success, error, warning. A success result indicates that the post was submitted successfully. Note that posts may not appear instantly after submission because the moderators of many groups may have additional automatic or manual review processes in place that can cause delays. An error result indicates that there is an error with the post that should be shown to the user and the message property will contain text describing the error. A warning result indicates that there is a warning about the post to show the user and the message property will contain a string describing the warning. A warning result doesn't prevent a post from being submitted, to continue the submission process after a warning result, just re-submit (with the updated session object) to temporarily override that specific warning.
  • session object: The updated session object that should override the client's copy of the session that was passed in the session parameter. Is null on success.

get_all_posts

This endpoint provides an easy way to get a feed of all the publicly published posts on trash nothing. It provides access to all publicly published offer and wanted posts from the last 30 days. The posts are sorted by date (newest first). There are fewer options for filtering, sorting and searching posts with this endpoint but there is no 1,000 post limit and posts that are crossposted to multiple groups are not merged together in the response. In most cases, crossposted posts are easy to detect because they have the same user_id, title and content.

trashnothing.get_all_posts({
  "types": "",
  "date_min": "",
  "date_max": ""
}, context)

Input

• input object
  • types required string: A comma separated list of the post types to return. The available post types are: offer, wanted
  • date_min required string: Only posts newer than or equal to this UTC date and time will be returned. The UTC date and time used must be within a day or less of date_max. And the date and time must be within the last 30 days. And the date and time must be rounded to the nearest second.
  • date_max required string: Only posts older than this UTC date and time will be returned. The UTC date and time used must be within a day or less of date_min. And the date and time must be rounded to the nearest second.
  • per_page integer: The number of posts to return per page (must be >= 1 and <= 50).
  • page integer: The page of posts to return.
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).

Output

• output object
  • posts array
    • items Post

get_all_posts_changes

This endpoint provides an easy way to get a feed of all the changes that have been made to publicly published posts on trash nothing. Similar to the /posts/all endpoint, only data from the last 30 days is available and the changes are sorted by date (newest first). Every change includes the date of the change, the post_id of the post that was changed and the type of change. The different types of changes that are returned are listed below. - deleted - undeleted - satisfied - promised - unpromised - withdrawn - edited - expired For edited changes, clients can use the retrieve post API endpoint to get the edits that have been made to the post.

trashnothing.get_all_posts_changes({
  "date_min": "",
  "date_max": ""
}, context)

Input

• input object
  • date_min required string: Only changes newer than or equal to this UTC date and time will be returned. The UTC date and time used must be within a day or less of date_max. And the date and time must be within the last 30 days. And the date and time must be rounded to the nearest second.
  • date_max required string: Only changes older than this UTC date and time will be returned. The UTC date and time used must be within a day or less of date_min. And the date and time must be rounded to the nearest second.
  • per_page integer: The number of changes to return per page (must be >= 1 and <= 50).
  • page integer: The page of changes to return.

Output

• output object
  • changes array
    • items object
      • date string: The UTC date and time when the post was changed.
      • post_id string
      • type string: The type of change. One of: deleted, undeleted, satisfied, promised, unpromised, withdrawn, edited, expired

get_post_client_javascript

Defines javascript functions that can be used to validate and submit posts.

The advantage of using these functions versus using the post submission endpoint directly is that some of the post validation checks can be done on the client side which will be faster.

NOTE: If used, this javascript file MUST be loaded dynamically for each user because the contents of the file are generated dynamically based on the current user. The file may be cached on a per user basis based on the HTTP cache headers that are returned when the file is requested (currently the cache headers specify that the file should expire after one day).

The following functions are available:

window.TN.check_crossposting_restrictions(group_ids)

Checks for crossposting restrictions when the user selects more than one group to post to.

Parameters:

• group_ids is an array of group IDs

Returns an object with three properties {allowed, restricted, restrictions}.

• allowed is an array of the group IDs from group_ids that can be crossposted to

• restricted is an array of the group IDs from group_ids that can't be crossposted to

• restrictions is an object mapping group IDs that have crossposting restrictions to arrays of group IDs that are restricted. It is useful for pinpointing why a group ID shows up in the restricted array so that users can be provided feedback about the reason for the crossposting restriction (eg. a message like 'group A doesn't allow crossposting to group B').

For example, given group_ids = 1, 2, 3, 4 and assuming group 1 doesn't allow posting to group 3 and group 2 doesn't allow posting to group 1, the returned object will be:

{allowed: 4, restricted: 1, 2, 3, restrictions: {1: 3, 2: 1}}

window.TN.submit_post(args, session, preferences, callback)

Submits a new post and performs validation checks on the post before it is accepted for submission.

Parameters:

• args is an object containing data about the post being submitted and must include the following properties:

  • type: The type of post. One of: offer, wanted
  • title: A short description of the item(s).
  • location: A short location description.

  The following properties are optional:

  • content: A longer description of the item(s).
  • group_ids: An array of group IDs to submit the post to (if any).
  • fair_offer: If set to 1, the post will be posted with the Fair Offer Policy (only valid for offer posts - see https://trashnothing.com/fair_offer_policy ).
  • photo_ids: A comma separated list of the IDs of the photos that should be attached to this post.
  • latitude
  • longitude

• session is a temporary object that is used by submit_post to store data about the submission process for a single post. The first time submit_post is called with a post, session should be a new empty object (eg. {}). The session object should be persisted until that post is successfully submitted and then it can be discarded so that the next post will start over with a new empty session object.

• preferences is a permanent object that the client persists and modifies based on warnings returned by the post submission process and user input. Some post warnings passed to the callback object have a preference_key string property so that users can opt out of those warnings in the future. To save this opt-out preference, set the property indicated by the preference_key in the preferences object (eg. preferencespreference_key = 1). The preferences object is only read by submit_post and never modified - it is up to the client to initialize, modify and persist the preferences object.

• callback is a function used to return the result of the post submission. It is called and passed one argument - an object with five properties {result, message, preference_key, identifier, session}. The result property is a string that is one of: success, error, warning. The identifier property is set for errors and warnings and will contain a string that represents the type of error or warning that occurred.

  A success result indicates that the post was submitted successfully. Note that posts may not appear instantly after submission because the moderators of many groups may have additional automatic or manual review processes in place that can delay the publishing of a post.

  An error result indicates that there is an error with the post to show the user and the message property will contain text describing the error.

  A warning result indicates that there is a warning about the post to show the user and the message property will contain a string describing the warning. A warning result doesn't prevent a post from being submitted, to continue the submission process after a warning result, just re-submit the post (with the updated session object) to temporarily override that specific warning.

  Certain types of warnings can be opted out of. These warnings will set preference_key to a string that can be set in the preferences object by the client to opt out of that type of warning in the future (see the description of the preferences parameter for more details).

trashnothing.get_post_client_javascript({
  "group_ids": "",
  "access_token": ""
}, context)

Input

• input object
  • group_ids required string: A comma separated list of all the group IDs that the current user is a member of. If the current user is not a member of any groups, simply pass an empty string.
  • callback string: The name of a global function to call once the script is loaded.
  • access_token required string: Passing the current users' OAuth2 access token as a GET parameter makes it easier to load this script in a normal HTML tag.

Output

Output schema unknown

get_posts_by_ids

Retrieve multiple posts

trashnothing.get_posts_by_ids({
  "post_ids": ""
}, context)

Input

• input object
  • post_ids required string: A comma separated list of the post IDs. If more than 10 post IDs are passed, only the first 10 posts will be returned.

Output

• output array
  • items Post

search_posts

Searching posts takes the same arguments as listing posts except for the addition of the search and sort_by parameters. 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.

trashnothing.search_posts({
  "search": "",
  "types": "",
  "sources": ""
}, context)

Input

• input object
  • search required string: The search query used to find posts.
  • sort_by string: How to sort the posts that are returned. One of: relevance, date Setting sort_by to date will sort posts from newest to oldest.
  • types required string: A comma separated list of the post types to return. The available post types are: offer, taken, wanted, received, admin
  • sources required string: 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: 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: The number of posts to return per page (must be >= 1 and <= 100).
  • page integer: The page of posts to return.
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).
  • latitude number: The latitude of a point around which to return posts.
  • longitude number: The longitude of a point around which to return posts.
  • radius number: 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: 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: Only posts older than this UTC date and time will be returned. If unset, defaults to the current date and time.
  • outcomes string: 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 are returned. If set to 'all', all posts will be returned no matter what outcome the posts have.
  • user_state string: 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.

Output

• output object
  • end_index integer: The index of the last post being returned (an integer between start_index and num_posts).
  • group_ids array: 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.
    • items string
  • num_pages integer: The total number of pages available.
  • num_posts integer: The total number of posts available.
  • page integer: The page number of the posts being returned.
  • per_page integer: The number of posts being returned per page.
  • posts array
    • items PostSearchResult
  • start_index integer: The index of the first post being returned (an integer between 1 and num_posts).

get_post

Retrieve a post

trashnothing.get_post({
  "post_id": ""
}, context)

Input

• input object
  • post_id required string: The ID of the post to retrieve.

Output

• output Post

update_post

Users can update posts to fix mistakes with their post, add photos, or add more details about the items. Updates should not be used to say that items in a post have been taken or received since the post satisfy endpoint is designed to do that.

trashnothing.update_post({
  "post_id": "",
  "type": "",
  "title": "",
  "location": "",
  "session": ""
}, context)

Input

• input object
  • post_id required string: The ID of the post to update.
  • type required string: The type of post. One of: offer, wanted
  • title required string: A short description of the item(s).
  • location required string: A short location description.
  • content string: A longer description of the item(s).
  • fair_offer integer: If set to 1, the post will be posted with the Fair Offer Policy (only valid for offer posts - see https://trashnothing.com/fair_offer_policy ).
  • latitude number: The latitude corresponding to the location description provided. If latitude and longitude are not provided, an attempt will be made to automatically geocode the location. If the location is unable to be geocoded, the post will be rejected and will have to be resubmitted with a latitude and longitude corresponding to the location or resubmitted with a different location that can be automatically geocoded. NOTE: The latitude and longitude should NOT be the users' exact location because we don't want to publicize their exact location unless their location description is their full address (which is not recommended). When a post is rejected because it can't be geocoded, the returned error will have its identifier property set to 'unknown-location'.
  • longitude number: The longitude corresponding to the location description provided. (see the NOTE in latitude description)
  • photo_ids string: A comma separated list of the IDs of the photos that should be attached to this post.
  • session required string: A JSON string representing a temporary object that is used to store data about the update process for a single post. The first time a post update is submitted, session should be a new empty object (eg. '{}'). The session object should be persisted by the client until that update is successfully submitted and then it can be discarded so that the next update will start over with a new empty session object. Every time an update is submitted and the response indicates that the submission was not successful, the session object returned in the response should override the clients copy of the session.
  • preferences string: A JSON string representing a permanent object that the client persists and modifies based on warnings returned by the update submission process and user input. Some warnings returned after submitting an update have a preference_key string property so that users can opt out of those warnings in the future. To save this opt-out preference, set the property indicated by the preference_key in the preferences object (eg. preferencespreference_key = 1). The preferences object is never modified by the server - it is up to the client to initialize, modify and persist the preferences object.

Output

• output object
  • identifier string: When an error or warning is returned, this will contain a short string representing the type of error or warning that occurred. Is null on success.
  • message string: Contains text describing the reason a post update was not successful. Is null on success.
  • preference_key string: Certain types of warnings can be opted out of. These warnings will set preference_key to a string that can be set in the preferences object by the client to opt out of that type of warning in the future (see the description of the preferences parameter for more details). Is null for errors, success and warnings that can't be opted out of.
  • result string: One of: success, error, warning. A success result indicates that the post update was submitted successfully. Note that post updates may not appear instantly after submission because the moderators of many groups may have additional automatic or manual review processes in place that can cause delays. An error result indicates that there is an error with the post that should be shown to the user and the message property will contain text describing the error. A warning result indicates that there is a warning about the post update to show the user and the message property will contain a string describing the warning. A warning result doesn't prevent a post update from being submitted, to continue the submission process after a warning result, just re-submit (with the updated session object) to temporarily override that specific warning.
  • session object: The updated session object that should override the client's copy of the session that was passed in the session parameter. Is null on success.

delete_bookmark

Delete a post bookmark

trashnothing.delete_bookmark({
  "post_id": ""
}, context)

Input

• input object
  • post_id required string

Output

Output schema unknown

bookmark_post

Bookmark a post

trashnothing.bookmark_post({
  "post_id": ""
}, context)

Input

• input object
  • post_id required string

Output

Output schema unknown

get_post_and_related_data

Retrieve a post and other data related to the post that is useful for displaying the post such as data about the user who posted the post and the groups the post was posted on.

trashnothing.get_post_and_related_data({
  "post_id": ""
}, context)

Input

• input object
  • post_id required string: The ID of the post to retrieve.

Output

• output object
  • author User
  • author_offer_count integer: Count of offer posts made by the post author in the last 90 days.
  • author_posts array: Other active posts from the post author in the last 90 days. A maximum of 30 posts will be returned.
    • items Post
  • author_wanted_count integer: Count of wanted posts made by the post author in the last 90 days.
  • bookmarked boolean: Whether or not the current user has bookmarked this post. Will be null for api key requests and for the current users' posts.
  • feedback array: Feedback the current user has left on the post author.
    • items Feedback
  • geolocate_bounds GeolocateBounds
  • groups array: The groups the post is published on.
    • items Group
  • post Post
  • replied boolean: Whether or not the current user has replied to this post. Will be null for api key requests and for the current users' posts.
  • user_can_reply boolean: Whether or not the current user (if any) can reply to this post. Unverified users cannot reply to posts until they verify their account.
  • viewed boolean: Whether or not the current user has previously viewed this post. Will be null for api key requests and for the current users' posts.

flag_post

Flags a post to be reviewed by the moderators.

trashnothing.flag_post({
  "post_id": "",
  "reason": ""
}, context)

Input

• input object
  • post_id required string
  • reason required string: The reason that this post is being flagged. Must be one of: 'spam', 'not free (for sale/trade/borrow)', 'illegal item', 'not family-friendly', 'other', 'mislabeled: is a Want', 'mislabeled: is an Offer'. NOTE: If reason is set to 'other', the details parameter is required to be set.
  • details string: An explanation from the current user for why they are flagging this post. This is useful for users to provide evidence or explain why there is a problem with the post. NOTE: If reason is set to 'other', details are required.

Output

Output schema unknown

geolocate_post

Map a post to a specific location when the post is missing a location or has an incorrect location.

trashnothing.geolocate_post({
  "post_id": "",
  "latitude": 0,
  "longitude": 0
}, context)

Input

• input object
  • post_id required string: The ID of the post to geolocate.
  • latitude required number
  • longitude required number
  • location string: A location name corresponding to the given latitude and longitude. Usually this is either a location included somewhere in the post title or content or a location description typed or selected by the user who is mapping the post.

Output

• output Post

promise_post

Mark an offer by the current user as promised to someone. This helps people viewing the post know that the items being offered may soon be given away as long as the person who was promised the items picks them up.

trashnothing.promise_post({
  "post_id": ""
}, context)

Input

• input object
  • post_id required string: The ID of the post to promise.

Output

• output Post

reply_to_post

Send a reply to a post from the current user to the post author.

trashnothing.reply_to_post({
  "post_id": "",
  "message": ""
}, context)

Input

• input object
  • post_id required string: The ID of the post to reply to.
  • message required string: The message to send to the post author.
  • send_copy integer: If set to 1, a copy of the reply will be emailed to the current user.
  • photo_ids string: A comma separated list of the IDs of the photos that should be attached to this reply.

Output

Output schema unknown

satisfy_post

Mark an offer or wanted post by the current user as satisfied (eg. an offer has been taken or a wanted has been received).

trashnothing.satisfy_post({
  "post_id": ""
}, context)

Input

• input object
  • post_id required string: The ID of the post to satisfy.

Output

• output Post

get_post_share_content

Retrieve text and html content useful for sharing a post by email.

trashnothing.get_post_share_content({
  "post_id": ""
}, context)

Input

• input object
  • post_id required string: The ID of the post to share.

Output

• output object
  • html string: Email body as html.
  • subject string: Email subject line text.
  • text string: Email body as plain text.

share_post

Forwards a copy of the post to the current user so that they can forward it to friends.

trashnothing.share_post({
  "post_id": ""
}, context)

Input

• input object
  • post_id required string: The ID of the post to share.

Output

Output schema unknown

unpromise_post

Mark an offer by the current user as unpromised.

trashnothing.unpromise_post({
  "post_id": ""
}, context)

Input

• input object
  • post_id required string: The ID of the post to unpromise.

Output

• output Post

withdraw_post

Mark an offer or wanted post by the current user as withdrawn.

trashnothing.withdraw_post({
  "post_id": ""
}, context)

Input

• input object
  • post_id required string: The ID of the post to withdraw.

Output

• output Post

get_stories

List stories

trashnothing.get_stories({}, context)

Input

• input object
  • page integer: The page of stories to return.
  • per_page integer: The number of stories to return per page (must be >= 1 and <= 50).
  • sort_by string: How to sort the stories that are returned. One of: date, distance, likes, views Setting sort_by to date will sort posts from newest to oldest. Setting sort_by to distance will sort posts from nearest to farthest. Setting sort_by to likes will sort posts with the most likes first. Setting sort_by to views will show the posts with the most views first.
  • latitude number: Find groups near the given latitude and longitude.
  • longitude number: Find groups near the given latitude and longitude.
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).

Output

• output object
  • stories array
    • items Story

submit_story

Submit a story

trashnothing.submit_story({
  "title": "",
  "content": "",
  "sharing": ""
}, context)

Input

• input object
  • title required string: The title of the story.
  • content required string: The content of the story.
  • sharing required string: Must be set to one of the following two options: public, members When sharing is set to public, anyone will be able to view the story. When sharing is set to members, only other members will be able to view the story.
  • photo_ids string: A comma separated list of the IDs of the photos that should be attached to this story.
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).

Output

• output Story

get_story

Retrieve a story

trashnothing.get_story({
  "story_id": ""
}, context)

Input

• input object
  • story_id required string: The ID of the story to retrieve.
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).

Output

• output Story

like_story

Like a story

trashnothing.like_story({
  "story_id": ""
}, context)

Input

• input object
  • story_id required string: The ID of the story to like.
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).

Output

• output Story

unlike_story

Unlike a story

trashnothing.unlike_story({
  "story_id": ""
}, context)

Input

• input object
  • story_id required string: The ID of the story to unlike.
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).

Output

• output Story

viewed_story

Records every time a user views the full story (and not just a preview or snippet),

trashnothing.viewed_story({
  "story_id": ""
}, context)

Input

• input object
  • story_id required string: The ID of the story viewed.

Output

Output schema unknown

get_current_user

Retrieve current user

trashnothing.get_current_user(null, context)

Input

This action has no parameters

Output

• output CurrentUser

update_current_user

Update the current user. All fields are optional so requests can update just one or multiple user properties at a time.

trashnothing.update_current_user({}, context)

Input

• input object
  • firstname string: The first name of the user.
  • lastname string: The last name of the user.
  • public_name integer: Whether or not the users' first and last name will be visible to other users. Set to 1 to enable and 0 to disable.
  • digest string: The frequency of digest emails sent to this user. One of: weekly, twice_weekly, daily, 12_hours, 8_hours, 6_hours, 4_hours, 2_hours, hourly To disable digests, set this to an empty string.
  • digest_photos integer: Whether or not to include photos in the digest emails. Set to 1 to enable photos and 0 to disable photos.
  • post_reminders integer: Whether or not the user will receive post reminder emails (to remind them to update or repost their posts). Set to 1 to enable and 0 to disable.
  • password string: A new password for the users' account. When setting a new password, the old_password parameter must be passed and set to the users' current password. NOTE: The password and old_password properties can NOT be used when the user property has_password is false. Instead, use the password reset endpoint to have a new password emailed to the user.
  • old_password string: The users current password. This is required when the user is changing their password.
  • profile_image_source string: The source of the users' profile image. The values this can be set to change dynamically based on the users' account. To get the values that can be used, use the source properties returned by the profile images endpoint.
  • last_listings_view string: The UTC date and time when the user last viewed the newest posts on the All Posts page.
  • public_post_sources string: A comma separated list of the sources to show public posts from. Currently only 'trashnothing' is supported.
  • show_all_group_posts integer: Set to 1 to show all group posts on the main posts page and in the digest emails. Set to 0 to only show group posts in the area defined by the users' location. Can only be set to 0 if the users' location is already set.
  • special_notices integer: Whether or not the user wants to receive special notice emails from the groups they are a member of. Special notices are admin posts that the group moderators choose to send out by email. Set to 1 to enable and 0 to disable.

Output

• output CurrentUser

get_alerts

List current users' email alerts

trashnothing.get_alerts(null, context)

Input

This action has no parameters

Output

• output array
  • items Alert

create_alert

Create an email alert

trashnothing.create_alert({
  "search": "",
  "types": ""
}, context)

Input

• input object
  • search required string: When a post matches this search query, an email alert will be sent. Must have a length >= 2 and < 255 characters.
  • types required string: A comma separated list of the post types that the alert should match against. The available post types are: offer, wanted

Output

• output Alert

delete_alert

Delete an email alert

trashnothing.delete_alert({
  "alert_id": ""
}, context)

Input

• input object
  • alert_id required string: The ID of the email alert to delete.

Output

Output schema unknown

change_email

Change the users' current email address. A verification link will be emailed to the new email address to verify that the email account belongs to the user. The email change will not take effect until the user clicks the link in the verification email.

trashnothing.change_email({
  "address": ""
}, context)

Input

• input object
  • address required string: The new email address.

Output

Output schema unknown

set_email_not_bouncing

Resets an email address bouncing state to false. The users' email address may be automatically marked as bouncing again if further emails sent to it are bounced.

trashnothing.set_email_not_bouncing(null, context)

Input

This action has no parameters

Output

• output CurrentUser

get_current_user_groups

List current users' groups

trashnothing.get_current_user_groups({}, context)

Input

• input object
  • membership string: Set the membership parameter to only return certain groups. The options are: - subscribed: Only return groups the user is a member of. - pending-questions: Only return groups where the user needs to respond to a new member questionnaire. - pending: Only return groups where the user is waiting for their membership request to be approved (excludes groups which are pending-questions). If unset, all groups the user is a member of and pending membership on will be returned.

Output

• output array
  • items Group

update_location

Update the current users' location. The location is used to determine which posts are shown to the user (both public posts and group posts).

trashnothing.update_location({
  "name": "",
  "latitude": 0,
  "longitude": 0,
  "radius": 0
}, context)

Input

• input object
  • name required string: A name that describes the location specified by the given latitude and longitude (must be <= 128 characters).
  • latitude required number
  • longitude required number
  • radius required number: A radius in meters that defines a circle around the point specified by latitude and longitude. Only posts within the area specified by this circle will be shown.

Output

• output CurrentUser

get_user_group_notices

List current users' group notices

trashnothing.get_user_group_notices({}, context)

Input

• input object
  • group_ids string: A comma separated list of group IDs to return notices for. If unset, notices for all the users groups will be returned.

Output

• output array
  • items GroupNotice

get_current_user_posts

NOTE: In order to make it easier to see all a users' posts, the current users' location preferences are not applied when listing or searching posts from a single user. If location based filtering of the posts is needed, the latitude, longitude and radius parameters may be used.

trashnothing.get_current_user_posts({
  "types": "",
  "sources": ""
}, context)

Input

• input object
  • types required string: A comma separated list of the post types to return. The available post types are: offer, taken, wanted, received, admin
  • sources required string: 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: 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: The number of posts to return per page (must be >= 1 and <= 100).
  • page integer: The page of posts to return.
  • device_pixel_ratio number: Client device pixel ratio used to determine thumbnail size (default 1.0).
  • latitude number: The latitude of a point around which to return posts.
  • longitud