Poster Network

Loading a Random Poster

If you want to load a completely random poster from the uploaded collection, load the base URL with no query parameters:

Filtering by Group

Posters can be uploaded for, and managed by, specific groups. You can filter posters by which group owns it:

These groups are available:

• group1: Group 1
• group2: Group 2
• group3: Group 3

Filtering by Poster Type

You can limit your selection to specific types of posters:

These types are available:

• advert: Advertisements
• dj: DJ Poster
• event: Events
• meme: Memes
• photography: Photography

Filtering by Collection

Posters can optionally be part of a "collection" to make them easy to reference in your worlds:

Filtering Expired Posters

By default, expired posters (like those for past events or ads) are hidden from the poster network. However, you can choose to include expired posters in your results by using the show_expired filter.

This example will include expired posters in the results. If you don't want to show expired posters, simply omit this filter, or set it to false:

This filter is especially useful for retrieving ads or events that have already passed but may still be relevant for archival purposes.

Billboard Mode (Syncing with board_id)

Billboard mode ensures that all users viewing the same board_id will see the same poster for up to 30 minutes. After that, the poster is soft-reset, meaning any new user request after the 30-minute window will trigger a new poster, which will then be synced across all users for another 30 minutes. Every 4 hours, the poster will hard-reset regardless of user activity to keep the content fresh.

• Soft Reset (30 minutes): If no new user requests have been made for the billboard in 30 minutes, a new poster will be assigned.
• Hard Reset (4 hours): Every 4 hours, regardless of user activity, the board will reset and display a new poster.

Example:

To request a poster tied to a specific board_id and sync it across users:

This ensures that any user visiting within the 30-minute soft reset period sees the same poster for that specific board.

Combining Billboard Mode with Filters:

You can also combine board_id with other filters like type or group. For example, to display only DJ posters on a synced billboard:

In this case:

• The board will only display posters of type "DJ".
• If no requests are made within 30 minutes, a new DJ poster will be fetched.
• After 4 hours, the poster will reset even if requests are still being made.

Filtering by User:

You can filter posters uploaded by a specific user using the user parameter:

You can also combine this with board_id to sync posters uploaded by a specific user across a billboard:

This ensures that all users will see posters uploaded by "Bluecyph" on that specific billboard.

Error Handling

The API will return a 404 error if no posters match your filters or if the board_id cannot find any available posters. For example, if no valid posters are found, you will receive: