FOAM Map Data

by Caleb Sheridan

FOAM provides the tools to enable a crowdsourced map. In this post, we share our experience using and providing this data for projects like FOAM Tools.

Data structure

Cartographer interactions on the FOAM Map data are originally stored in one of two places:

  1. Off-chain. Text-heavy data, like a point's description, is stored on IPFS.
  2. On-chain. More constrained data, like a point's listing hash, is available directly from FOAM's smart contracts.

FOAM's smart contracts are well-constructed and it may be possible to fetch the data you need directly from a node or a service like Infura.

Third-party options

Depending on your use case, pulling data directly from Ethereum and IPFS may not be reasonably feasible or even possible. Third-party options are convenient given the tradeoff of not being trustless. These options offer quick, efficient queries.

# Data source Link Best for
1 FOAM API Go there Current map state and metadata
2 Blocklytics API Go there Historical map state
3 FOAM Subgraph Go there Real-time map state and stats

FOAM API - What you need to know

The most common queries we use are to get a point's metadata using its listing hash or to search an area for nearby points.

  • Review endpoints with Swagger UI
  • See /poi/{listing_hash}
  • See /search/poi

Examples of visualizing FOAM Map API data are also available from the developer docs.

FOAM Map API Examples (https://f-o-a-m.github.io/foam.developer/examples/foam_map_api.html)

Blocklytics API - What you need to know

We use this for historical data and big summary tables on FOAM Tools. Our data structure stores on-chain and off-chain data together to make fetches involving point metadata more efficient than querying the FOAM Map API repeatedly.

  • You'll need to email us for a key (hello@blocklytics.org)
  • If you need the data served in different ways, we may be able to help.

FOAM Subgraph - What you need to know

Subgraphs serve on-chain data quickly and efficiently. You'll need to use GraphQL to query the subgraph and explore the schema to make full use of the resource.

  • Explore the sample queries
  • Off-chain data (point metadata) is not available from the subgraph

More information

Leave us feedback or ask for more information through our social channels: Discord, Twitter, Email.