---
title: "Lookup API - Sorted wiki"
description: "Ask Sorted what is in the player's containers: totals, positions, highlights and single containers."
url: https://voxelsprout.com/sorted/wiki/lookup-api
---

[Sorted](https://voxelsprout.com/sorted) [Wiki](https://voxelsprout.com/sorted/wiki)Lookup API

# Lookup API

Ask Sorted what is in the player's containers: totals, positions, highlights and single containers.

`SortedLookup` answers from Sorted's [Chest memory](https://voxelsprout.com/sorted/wiki/chest-memory): what the player has opened, or what Sorted has read. Its own search runs on it, and [BuildPrint](https://voxelsprout.com/buildprint) uses it for its material list. From Sorted **0.1.13**; `contentsAt`, `lastSeenAt` and `claimGlance` from **0.1.21**.

The answer is what Sorted last saw. In singleplayer that is always current. On a server another player may have changed a chest since, and `isTrustworthy()` tells the two apart. Show stored counts apart from what the player is carrying.

## Before you call it

Call it on the client thread. `isAvailable()` is false when Sorted is off on this server or no world is loaded. Every call then returns nothing rather than throwing, so a missed check means "found nothing", not a crash.

## Count items

```java
if (SortedLookup.isAvailable()) {
    // Item id -> how many are stored, within 64 blocks. Items with none are left out.
    Map<String, Integer> stored = SortedLookup.countAll(
            List.of("minecraft:oak_planks", "minecraft:glass"), "AREA");
    int planks = stored.getOrDefault("minecraft:oak_planks", 0);
}
```

| Scope  | How far                                                                                |
| ------ | -------------------------------------------------------------------------------------- |
| NEARBY | Within 8 blocks, and 8 up or down: the room the player is in.                          |
| AREA   | Within 64 blocks, any height: a base.                                                  |
| LOADED | Within the render distance.                                                            |
| WORLD  | Every container Sorted remembers in this world. Also what an unknown scope name means. |

## Find and highlight

```java
SortedFind glass = SortedLookup.find("minecraft:glass", SortedScope.AREA);
if (glass != null) {
    for (SortedFind.SortedLocation at : glass.locations()) {
        // at.pos(), at.count(), at.containerName(), at.lastSeen()
    }
    SortedLookup.highlight(glass.positions()); // outline them through walls
}

// Or the same in one plain-typed call: highlights, and says in how many containers.
int containers = SortedLookup.locate("minecraft:glass", "AREA");
```

## One container

```java
String dim = level.dimension().identifier().toString();
Map<String, Integer> inside = SortedLookup.contentsAt(dim, pos.asLong());
if (inside == null) {
    // Not seen yet, or out of date since another player opened it.
} else {
    long when = SortedLookup.lastSeenAt(dim, pos.asLong()); // System.currentTimeMillis() then
}
```

Either half of a large chest answers for the whole chest. Counts are by item id, so a renamed or enchanted stack counts as its plain item.

## Take over a label

If your mod shows something more specific on a container, claim it, and Sorted leaves its own label off there. BuildPrint does this to show what a schematic wants inside a chest.

```java
// Every second or so while you show your own label on these containers.
// A claim lapses after a few seconds, so Sorted's labels come back if you stop.
SortedLookup.claimGlance("mymod", dim, List.of(pos.asLong()));

// Done: an empty list releases the claim at once.
SortedLookup.claimGlance("mymod", dim, List.of());
```

## Reference

| SortedLookup                                                            | What it does                                                        |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------- |
| isAvailable()                                                           | Sorted is running, in a world, and not off on this server.          |
| isTrustworthy()                                                         | True in singleplayer, where stored counts cannot be out of date.    |
| indexedContainers()                                                     | How many containers Sorted remembers in this world.                 |
| search(String query, SortedScope scope)                                 | Items whose name or id contains the text, most first.               |
| find(String itemId, SortedScope scope)                                  | One item: its total and every container holding it, or null.        |
| findAll(Collection<String> itemIds, SortedScope scope)                  | Several items in one pass. Use this for a list, not find in a loop. |
| countAll(Collection<String> itemIds, String scope)                      | findAll reduced to id and total, plain types only.                  |
| locate(String itemId, String scope)                                     | Highlight the containers holding an item. Returns how many.         |
| highlight(Collection<BlockPos> positions) / clearHighlight()            | Outline containers through walls for a few seconds, or stop.        |
| contentsAt(String dimension, long pos)                                  | Item id and count in one container, or null when not known.         |
| lastSeenAt(String dimension, long pos)                                  | When that was, or 0.                                                |
| claimGlance(String owner, String dimension, Collection<Long> positions) | Take the label on these containers for a few seconds.               |

[Previous Storage API](https://voxelsprout.com/sorted/wiki/storage-api)

Something missing or wrong on this page? Say so on [Discord](https://discord.gg/CvdkGbEW4y).