Getting Started with the Core Library

WARNING

This page is for developers looking to build applications or interfaces to the Protovoters library. For end users looking to utilize Protovoters, visit Getting Started with the CLI.

Prerequisites

• Node.js (other runtimes are currently not supported)
• Terminal/Command Prompt
• JavaScript or TypeScript project

Installation

From the project directory, run the following in your terminal:

npm

$ npm install @protovoters/core

pnpm

$ pnpm install @protovoters/core

yarn

$ yarn add @protovoters/core

Then import the library into your project:

import * as Protovoters from "@protovoters/core";

Builders

Builders (VoterFileBuilder) are objects that build voter files which can be iterated upon directly or written to disk.

Creation

When instantiating a builder, you need to select a either a bounding box, GeoJSON Polygon, or a specified political division by OCD Division ID.

OCD division

const builder = await Protovoters.for("ocd-division/country:us/state:tx/county:travis");

bbox

const builder = await Protovoters.forBbox({
  xMin: -98.172985,
  yMin: 30.024504,
  xMax: -97.369547,
  yMax: 30.628254,
});

GeoJSON

import polygon from "./my-area.geojson" with { type: "json" };

const builder = await Protovoters.forPolygon(polygon);

Usage

Write to disk

const outPath = await builder.to("voters.fgb");

To track progress, use the onFeature callback:

await builder.to("voters.fgb", {
  onFeature: (count) => console.log(`Processed ${count} voters`),
});

Iteration

VoterFileBuilder is an async iterable, so you can loops to iterate through voters:

for await (const voter of builder) {
  console.log(voter.voter, voter.lon, voter.lat);
}

Divisions

Listing

To list divisions, use the .divisions export:

const divisions = Protovoters.divisions;

OCD-ID <-> Division Paths

Internally, the library uses division paths to find loaders. To convert a path to an OCD Division ID, use the ocdId function:

Protovoters.ocdId("country-us/state-tx/travis");