Pre-geocoded ballot lookups

Use a pre-geocoded location when your application already has reliable latitude and longitude coordinates for a voter address.

This option bypasses Branch's geocoding provider. Branch uses the supplied coordinates to match the voter to districts, then generates the ballot normally.

Request format

Send a location object when creating a ballot:

{
  "location": {
    "latitude": 33.7866,
    "longitude": -84.3831,
    "address": "730 Peachtree St NE, Atlanta, GA 30308",
    "addressComponents": {
      "city": "Atlanta",
      "county": "Fulton County",
      "state": "GA",
      "zip": 30308
    }
  },
  "election": "ga-2026-general-election"
}

The location object requires:

• latitude: a number from -90 through 90
• longitude: a number from -180 through 180
• address: a complete, human-readable address to store and display with the ballot

addressComponents is optional. When available, include components such as city, county, state, and zip to improve the resolved address data.

Do not combine location with street, placeId, sessionToken, lat, or long in the same request.

Coordinate responsibility

Branch does not verify or geocode the supplied address when location is used. Your application is responsible for ensuring that the coordinates correspond to the human-readable address.

District matching is based primarily on the supplied coordinates. The ballot response contains the supplied address plus normalized or backfilled address components when available.

Usage and analytics

Pre-geocoded requests do not increment billable API ballot lookup usage because they do not use Branch's geocoding flow.

Successful requests still count toward standard ballot lookup analytics.

For the complete request and response schemas, see the create ballot API specification.