Node.js JavaScript & TypeScript bindings for Google S2.
S2 is a library from Google for easily storing, indexing, and retrieving geographic locations.
Geographic regions can be indexed by S2 cell ids of various levels in a data store and then later retrieved by these ids for extremely quick geolocation lookups.
The goal of this library is to maintain Node.js TypeScript bindings for the latest version of Google's C++ S2 library.
Other JavaScript projects available on GitHub appear unmaintained.
The project has been built against Node's N-API, meaning that it's compatible across Node.js versions that support BigInt. This means that Node.js version 9 and below are unsupported.
As of today, the library is built and tested against Node.js 20, 22 and 24. The library has been in production use at Radar and has been built against OS X and Linux. Feel free to open an issue or PR if you'd like other platform support.
See test.sh for more details.
To install:
npm install @radarlabs/s2
To run tests (you'll need Docker):
./test.shS2 Cells can be generated from BigInt S2 IDs or string tokens:
consts2=require('@radarlabs/s2');constcell1=news2.CellId(9926595695177891840n);console.log(cell1.token());>89c25a31constcell2=news2.CellId('89c25a31');console.log(cell2.id());>9926595695177891840nTo generate a covering for a given area:
consts2=require('@radarlabs/s2');
# anarrayoflat/lngpairsrepresentingaregion(apartofBrooklyn,inthiscase)constloopLLs=[[40.70113825399865,-73.99229764938354],[40.70113825399865,-73.98766279220581],[40.70382234072197,-73.98766279220581],[40.70382234072197,-73.99229764938354]];
# maptoanarrayofnormalizeds2.LatLngconsts2LLs=loopLLs.map(([lat,lng])=>(news2.LatLng(lat,lng)));
# generates2cellstocoverthispolygonconsts2level=14;constcovering=s2.RegionCoverer.getCoveringTokens(s2LLs,{min: s2level,max: s2level});covering.forEach(c=>console.log(c));>89c25a31>89c25a33>89c25a35>89c25a37
# checkifapointiscontainedinsidethisregionconstpoint=news2.CellId(news2.LatLng(40.70248844447621,-73.98991584777832));constpointAtLevel14=point.parent(s2level);console.log(pointAtLevel14.token());>89c25a31constcoveringSet=newSet(covering);console.log(coveringSet.contains(pointAtLevel14.token()));>trueTo generate a covering for a given radius around a point:
consts2=require('@radarlabs/s2');
# makeanS2latlngobjectfordowntownSanDiegoconsts2LatLong=news2.LatLng(32.715651,-117.160542);
# setcellcoveringoptionssothebiggestregionisa6andsmallestisa13,andlimitto10cellsconstcellCoveringOptions={min: 6,max: 13,max_cells: 10};
# getthecells(withthesizerangeallowed)coveringa10,000metersearchradiuscenteredonthegivenlocation
# NotethatthiscallreturnsaCellUnionobjectinsteadofalistoftokens,whichisusefulforcomparisonsconstcoveringCells=s2.RegionCoverer.getRadiusCovering(s2LatLong,10000,cellCoveringOptions);
# Forthisexamplethough,we'll loop over the cellIds within the CellUnion and get their tokens
console.log(coveringCells.cellIds().map((cellId)=>cellId.token()));>80d94d>80d951>80d953>80d955>80d956c>80dbffc>80dc01>80deab>80dead>80deb2ac
# the"coveringCells"CellUnionislikethe"coveringSet"fromthepreviousexample,socanbeuseddirectlywithoutconvertingtoaset
# testbycheckingacellcenteredatourlatlongconsole.log(coveringCells.has(news2.CellId(s2LatLong)));>trueHere's a visualization of the above set of covering cells. The center of the 10k radius is in downtown San Diego.
Check if a cell is contained in another:
constc1=s2.CellId.fromToken('89c25a37')constc2=s2.CellId.fromToken('89c25')c2.contains(c1)>truec1.contains(c2)>falseIf you'd like to see more functionality, feel free to open an issue or create a pull request.
More detailed usage can be found in the tests folder.
The Node S2 is library is at its infancy, so APIs are likely to change. In order to help with versioning, we publish TypeScript bindings so that your compiler can check if anything has changed. To keep up with updates, see CHANGELOG.md