Skip to content
FIRMSapi Docs

Search, autocomplete and nearby

Section titled “Search”

GET /v1/search?q=… does a fuzzy search over facility name, street address, city and state, and ranks the results with a relevance score from 0 to 100. Typos, word order and abbreviations (ST/STREET, AVE/AVENUE, INTL/INTERNATIONAL) are fine.

Terminal window
curl -G https://api.firmsapi.com/v1/search -H "x-api-key: $FIRMSAPI_KEY" \
  --data-urlencode "q=231 tyler st newark"
{
  "data": [
    { "code": "F577", "name": "PORT NEWARK CONTAINER TERMINAL LLC", "status": "active", "score": 100.0, "...": "..." }
  ],
  "meta": { "count": 1, "data_as_of": "2026-10-23", "mode": "live", "...": "..." }
}
Parameter Default
q required Name and/or address, 2 to 200 characters. A code works too.
state 2-letter state, e.g. NJ
port 4-digit CBP port code, e.g. 4601
type Facility type codes, comma-separated, e.g. 03,04
include_deleted false Include deleted codes, ranked after active ones
limit 10 1 to 50

Placeholders and CBP test records never appear in search results.

Autocomplete

Section titled “Autocomplete”

GET /v1/autocomplete?q=… matches the start of words, for type-ahead inputs, and returns compact items. Get the full record with GET /firms/{code}.

Terminal window
curl -G https://api.firmsapi.com/v1/autocomplete -H "x-api-key: $FIRMSAPI_KEY" --data-urlencode "q=maher t"
{
  "data": [
    { "code": "E430", "name": "MAHER TERMINAL", "city": "Elizabeth", "state": "NJ", "port": "4601", "type": "03", "status": "active" }
  ],
  "meta": { "count": 1, "...": "..." }
}

Takes the same filters as search; q can be a single character and limit is 1 to 20 (default 8). Autocomplete requests do not count toward your monthly calls. Still debounce keystrokes (300 ms or so), and call your own backend, not the API, from the browser so your key stays secret.

Nearby

Section titled “Nearby”

GET /v1/nearby finds facilities within radius_km of a point, a facility or an address, nearest first, with distance_km.

Terminal window
# around a point
curl -G https://api.firmsapi.com/v1/nearby -H "x-api-key: $FIRMSAPI_KEY" -d lat=40.68 -d lon=-74.15 -d radius_km=5
# around another facility (it is left out of the results)
curl -G https://api.firmsapi.com/v1/nearby -H "x-api-key: $FIRMSAPI_KEY" -d code=E430 -d type=04
# around an address
curl -G https://api.firmsapi.com/v1/nearby -H "x-api-key: $FIRMSAPI_KEY" \
  --data-urlencode "address=1 World Trade Center, New York, NY 10007" -d radius_km=25

Pass exactly one of these:

Parameter
lat, lon The point. Pass both.
code Search around this facility. 404 if it does not exist or has no location.
address A US street address, e.g. 231 Tyler St, Newark, NJ 07114. Commas help but are optional; include the city and state or ZIP. 404 if it cannot be located.

And optionally:

Parameter Default
radius_km 10 Up to 100
type, include_deleted As in search
limit 20 1 to 100

meta.origin tells you which point distances are measured from and how it was found:

"origin": {
  "lat": 40.71163, "lon": -74.01236, "source": "geocoder",
  "label": "1 World Trade Center, New York, NY 10007-0089, United States",
  "code": null, "relevance": 1.0, "place_type": "PointAddress"
}
source
point Your lat and lon
code That facility’s location
firms_address The address is a FIRMS facility’s, so we used its stored location; code names it. Facilities at that address come back with distance_km: 0.
geocoder We geocoded the address. Check place_type and relevance: a Locality or PostalCode match is the middle of a city or ZIP, not a building.

A nearby search counts as one call whichever origin you use. With a test key, address only finds the addresses of the fixture facilities (try 231 Tyler St, Newark, NJ 07114); other addresses return 404.

Facilities whose address could not be geocoded have no location and never appear in nearby results.