Geocoding API

Every lookup, the fields you need.

Send addresses and get back points, or send points and get back the nearest address.

Every lookup returns the coordinates, the address, state, county, city or township and ZIP code for 1 point. Add the census tract, or the FEMA flood zone and coastal risk, for 1 more point each.

POST https://api.pricedna.co/v1/geocode POST https://api.pricedna.co/v1/reverse
2
Endpoints
System status
100
Rows per request
2,500
Free points a day

Quick start

Send up to 100 addresses. Each row says how it was placed, or why it wasn’t.

Authenticate with your key in the X-PriceDNA-API-Key header.

curl -X POST https://api.pricedna.co/v1/geocode \
  -H "X-PriceDNA-API-Key: $PRICEDNA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      "123 Union St S, Concord, NC 28025",
      "1 Nowhere Ln, Concord, NC 28025"
    ],
    "census": true,
    "flood": true
  }'

Addresses to points

POST /v1/geocode places each address you send.

Headers
FieldDescription
X-PriceDNA-API-Key string required Your secret API key. Keep it server-side only.
Content-Type string required application/json
Idempotency-Key string Send the same key to retry safely. Within 24 hours, a repeat returns the first answer, marked Idempotent-Replayed: true, with no second charge.
Body
FieldDescription
addresses array required US addresses as text: house number, street, city or ZIP, and state. One row comes back for each, in the same order.1 to 100 per request
census boolean Add each row’s census tract (tract): 1 more point a row.
flood boolean Add each row’s flood zone and coastal risk (flood): 1 more point a row.

The response

One row per address, in the order sent. Here one address was placed and one was not.

{
  "results": [
    {
      "input": "123 Union St S, Concord, NC 28025",
      "status": "placed",
      "reason": null,
      "message": null,
      "address": "123 Union St S, Concord, NC 28025",
      "lat": 35.408416,
      "lng": -80.578372,
      "accuracy": "neighbor_interpolated",
      "state": { "abbr": "NC", "name": "North Carolina" },
      "county": { "fips": "37025", "name": "Cabarrus County" },
      "city": "Concord",
      "township": null,
      "zip": "28025",
      "tract": { "geoid": "37025042202", "number": "422.02" },
      "tribal_land": null,
      "flood": {
        "zone": null,
        "risk": "minimal",
        "in_high_risk_zone": false,
        "coastal_county": false,
        "coastal_flood_risk": null
      }
    },
    {
      "input": "1 Nowhere Ln, Concord, NC 28025",
      "status": "not_found",
      "reason": "unknown_street",
      "message": "We can't find this street yet. If it's new, enter a nearby address.",
      "address": null,
      "lat": null,
      "lng": null,
      "accuracy": null,
      "state": null,
      "county": null,
      "city": null,
      "township": null,
      "zip": null,
      "tract": null,
      "tribal_land": null,
      "flood": null
    }
  ],
  "points_used_today": 6,
  "points_left_today": 2494,
  "points_per_day": 2500,
  "points_purchased_left": 0,
  "resets_at": "2026-11-11T00:00:00-05:00"
}

Points to addresses

POST /v1/reverse describes each point you send and names the nearest address within 100 meters.

Headers
FieldDescription
X-PriceDNA-API-Key string required Your secret API key. Keep it server-side only.
Content-Type string required application/json
Idempotency-Key string Send the same key to retry safely. Within 24 hours, a repeat returns the first answer, marked Idempotent-Replayed: true, with no second charge.
Body
FieldDescription
points array required Points in the United States. One row comes back for each, in the same order.1 to 100 per request
points[].lat number required Latitude in decimal degrees.
points[].lng number required Longitude in decimal degrees.
census boolean Add each row’s census tract (tract): 1 more point a row.
flood boolean Add each row’s flood zone and coastal risk (flood): 1 more point a row.

The request and response

The same fields as a forward row, plus nearest_address.

{
  "points": [ { "lat": 35.408416, "lng": -80.578372 } ]
}
{
  "results": [
    {
      "input": { "lat": 35.408416, "lng": -80.578372 },
      "status": "placed",
      "reason": null,
      "message": null,
      "address": null,
      "lat": 35.408416,
      "lng": -80.578372,
      "accuracy": null,
      "state": { "abbr": "NC", "name": "North Carolina" },
      "county": { "fips": "37025", "name": "Cabarrus County" },
      "city": "Concord",
      "township": null,
      "zip": "28025",
      "tract": null,
      "tribal_land": null,
      "flood": null,
      "nearest_address": {
        "address": "133 Union St S, Concord, NC 28025",
        "meters": 0
      },
      "nearest_address_unavailable": false
    }
  ],
  "points_used_today": 1,
  "points_left_today": 2499,
  "points_per_day": 2500,
  "points_purchased_left": 0,
  "resets_at": "2026-11-11T00:00:00-05:00"
}

Rows

Every row has every field, in the same order. A field that doesn’t apply is null.

Row fields
FieldDescription
input any What you sent for this row, as sent.
status enum Whether the row was placed. Every status but error is charged its points.placed · not_found · invalid · outside_coverage · error
reason enum Why a row was not placed. Null when it was. Every reason is in the Reasons table below.number_out_of_range · unknown_street · not_found · incomplete · not_text · bad_point · outside_coverage · lookup_unavailable · lookup_failed · timeout
message string The reason in plain words. Null when the row was placed.
address string The address as placed. Null on reverse rows; see nearest_address.
lat number Latitude in decimal degrees.
lng number Longitude in decimal degrees.
accuracy enum How the address was placed. Null on reverse rows, where the point is yours.address_point · park · neighbor_interpolated · street_range · street_range_extended
state object The state.
state.abbr string Two-letter state code, such as NC.
state.name string State name.
county object The county, or the county equivalent such as a parish or borough.
county.fips string Five-digit county FIPS code.
county.name string County name, such as Cabarrus County.
city string The city, town or village the point is in. Null outside one.
township string The town or township, where it is a separate place from the city.
zip string The five-digit ZIP code area the point is in.
tract object The census tract, with "census": true. Null otherwise.
tract.geoid string The tract’s 11-digit census code: state, county and tract.
tract.number string The tract number as the Census Bureau writes it, such as 406 or 11.01.
tribal_land string The tribal jurisdiction’s name on tribal land. Null elsewhere.
flood object FEMA flood zone and coastal risk at the point, with "flood": true. Null otherwise.
flood.zone string FEMA’s zone code at the point for high-risk, moderate-risk and undetermined zones, such as AE or D. Null elsewhere.
flood.risk enum The flood risk FEMA’s map gives the point.high · moderate · undetermined · minimal · not_mapped · unknown
flood.in_high_risk_zone boolean True inside a FEMA high-risk zone. Null when the risk is unknown.
flood.coastal_county boolean True when the county touches the open coastline, ocean, Gulf or Great Lakes (Census Bureau TIGER/Line coastline), or FEMA's National Risk Index rates coastal flooding in it, which covers bays, harbors and estuaries.
flood.coastal_flood_risk enum The census tract’s coastal flooding rating from FEMA’s National Risk Index. Null where coastal flooding doesn’t apply.very_high · relatively_high · relatively_moderate · relatively_low · very_low · not_rated
nearest_address object Reverse rows only: the closest address within 100 meters, and how far. Null past that, or when the search couldn’t finish.
nearest_address.address string The closest address to the point.
nearest_address.meters number How far it is from the point.
nearest_address_unavailable boolean Reverse rows only: true when the search for the nearest address couldn’t finish, so a null nearest_address doesn’t mean none within 100 meters. Null on rows that weren’t placed.

Statuses

Each row says it was placed, or why not. Never a silent guess.

Statuses
StatusReasonsCharged its pointsMeaning
placed null Yes Placed. Every field is filled where it applies.
not_found number_out_of_range unknown_street not_found Yes A complete address we could not place. message says why, with the known house numbers when the number is out of range.
invalid incomplete not_text bad_point Yes Not an address or point we can read.
outside_coverage outside_coverage Yes Outside the 50 states and DC.
error lookup_unavailable lookup_failed timeout No We couldn’t read our own address data (lookup_unavailable), the lookup failed (lookup_failed), or the request ran out of time before this row (timeout). Send it again.

Reasons

Why a row was not placed, and the message we send with it.

Reasons
ReasonStatusMessage
number_out_of_range not_found Names the house numbers we know on that street, such as: We don't know 290 on Main St in Springfield. Known numbers run from 100 to 199. Check the address and try again.
unknown_street not_found “We can't find this street yet. If it's new, enter a nearby address.”
not_found not_found “We couldn't find that address.”
incomplete invalid “Enter the full address: house number, street, city or ZIP, and state.”
not_text invalid “Send the address as text: house number, street, city or ZIP, and state.”
bad_point invalid “Send a latitude and longitude in the United States.”
outside_coverage outside_coverage “We cover addresses in the 50 states and DC.”
lookup_unavailable error “We couldn't finish this lookup. Send it again in a minute.”
lookup_failed error “We couldn't finish this lookup. Send it again in a minute.”
timeout error “We ran out of time before this row. Send it again; it was not counted.”

Accuracy

How each address was placed, from the most exact.

Accuracy
ValueMeaning
address_point A stored point for this very address.
park A national park’s own coordinates.
neighbor_interpolated Between neighbors’ stored points on the same side of the street.
street_range Along the street, from its range of house numbers.
street_range_extended Just past the street’s known house numbers. An estimate.

Flood risk

From FEMA’s National Flood Hazard Layer. Not an official flood zone determination. Coastal county from the Census Bureau TIGER/Line coastline; coastal flooding rating from FEMA’s National Risk Index.

Flood risk
ValueMeaning
high In a FEMA high-risk zone (A or V zones).
moderate In a moderate-risk zone.
undetermined In a zone where FEMA has not determined the risk (D).
minimal Mapped, with minimal risk.
not_mapped FEMA has no flood map for the point.
unknown The flood map could not be read for this lookup. Send it again.

What’s included

The Free plan includes 2,500 points a day. Paid plans include more.

  • 1 point per lookup, plus 1 per enrichment (census, flood) on a row we place.
  • A row we don’t place costs its 1 point. Rows we couldn’t finish aren’t charged.
  • One count across the API and the site, reset at midnight Eastern time.
  • Up to 100 rows per request.
  • On Standard and Pro, points from packs are used once today’s are gone. Packs carry over while your account is open.
  • A request that needs more points than you have left, today and in packs, is refused whole, and nothing is charged.

See paid plans

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 18000

{
  "type": "https://www.pricedna.co/api#error-no-points-left-today",
  "title": "No points left today",
  "status": 429,
  "detail": "This request needs 300 points and you have 40 points left today. They reset at midnight Eastern time.",
  "code": "DAILY_POINTS_USED",
  "points_left": 40,
  "points_needed": 300,
  "resets_at": "2026-11-11T00:00:00-05:00",
  "points_per_day": 2500,
  "points_purchased_left": 0
}

Errors

Errors arrive as problem details (RFC 9457), the same for all three APIs. See every error type.

Ready to start building?

Get your free API key