Get a port and its facilities

GET

/ports/{port}

const url = 'https://api.firmsapi.com/v1/ports/4601?include_deleted=false&limit=100';
const options = {method: 'GET', headers: {'x-api-key': '<x-api-key>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.firmsapi.com/v1/ports/4601?include_deleted=false&limit=100' \
  --header 'x-api-key: <x-api-key>'

Facilities are ordered by code and paged with cursor. Placeholders are left out.

Authorizations

apiKey

Parameters

Path Parameters

port

required

Port

4-digit CBP port code.

string

/^[0-9]{4}$/

4-digit CBP port code.

Query Parameters

type

Any of:

string
null

string

/^(0[1-9]|1[01])(,(0[1-9]|1[01]))*$/

Facility type codes, comma-separated (e.g. 03,04).

include_deleted

Include Deleted

Include deleted codes (ranked after active ones).

boolean

Include deleted codes (ranked after active ones).

limit

Limit

integer

default: 100 >= 1 <= 500

cursor

Any of:

string
null

string

/^[A-Za-z0-9]{4}$/

next_cursor from the last page.

Responses

200

application/json

PortResponse

object

data

required

PortDetail

object

code

required

Code

string

name

required

Any of:

string
null

string

state

required

Any of:

string
null

string

region

required

Any of:

string
null

string

facility_count

required

Facility Count

integer

active_count

required

Active Count

integer

facilities

required

Facilities

One page of the port’s facilities, ordered by code.

Array<object>

Facility

object

code

required

Code

4-character FIRMS code.

string

name

required

Name

string

status

required

Status

Deleted codes stay in the data so you can tell why a filing failed.

string

Allowed values: active deleted

type

required

Any of:

FacilityType
null

FacilityType

object

code

required

Code

string

label

required

Label

string

address

required

Address

object

street

required

Any of:

string
null

string

city

required

Any of:

string
null

string

state

required

Any of:

string
null

string

zip

required

Any of:

string
null

string

port

required

Any of:

PortRef
null

PortRef

object

code

required

Code

string

name

required

Any of:

string
null

string

region

required

Any of:

string
null

string

location

required

Any of:

Location
null

Location

object

lat

required

Lat

number

lon

required

Lon

number

quality

required

Any of:

string
null

string

junk

required

Junk

True for “DO NOT USE” placeholders and CBP test records.

boolean

first_seen

required

Any of:

string
null

string

last_changed

required

Any of:

string
null

string

meta

required

PageMeta

object

data_as_of

required

Any of:

string
null

string

source

required

Any of:

string
null

string

mode

required

Any of:

string
null

string

Allowed values: live test

build_id

Any of:

string
null

string

request_id

Any of:

string
null

string

count

required

Count

Items in data.

integer

next_cursor

Any of:

string
null

string

Example

{
  "data": {
    "code": "4601",
    "facilities": [
      {
        "code": "E430",
        "name": "MAHER TERMINAL",
        "status": "active",
        "type": {
          "code": "03",
          "label": "Pier or terminal"
        },
        "port": {
          "code": "4601",
          "name": "Newark/Elizabeth"
        }
      }
    ]
  },
  "meta": {
    "mode": "live"
  }
}

400

Invalid request (not counted).

application/json

ErrorResponse

object

error

required

ErrorBody

object

code

required

Code

Stable, machine-readable error code.

string

message

required

Message

string

links

required

Links

docs always; billing, buy_pack, upgrade when they help.

object

key

additional properties

string

details

Details

meta

Any of:

Meta
null

Meta

object

data_as_of

required

Any of:

string
null

string

source

required

Any of:

string
null

string

mode

required

Any of:

string
null

string

Allowed values: live test

build_id

Any of:

string
null

string

request_id

Any of:

string
null

string

Example

{
  "error": {
    "code": "quota_exceeded"
  },
  "meta": {
    "mode": "live"
  }
}

401

Missing, invalid or revoked API key.

application/json

ErrorResponse

object

error

required

ErrorBody

object

code

required

Code

Stable, machine-readable error code.

string

message

required

Message

string

links

required

Links

docs always; billing, buy_pack, upgrade when they help.

object

key

additional properties

string

details

Details

meta

Any of:

Meta
null

Meta

object

data_as_of

required

Any of:

string
null

string

source

required

Any of:

string
null

string

mode

required

Any of:

string
null

string

Allowed values: live test

build_id

Any of:

string
null

string

request_id

Any of:

string
null

string

Example

{
  "error": {
    "code": "quota_exceeded"
  },
  "meta": {
    "mode": "live"
  }
}

404

Not found (counted: it is a lookup result).

application/json

ErrorResponse

object

error

required

ErrorBody

object

code

required

Code

Stable, machine-readable error code.

string

message

required

Message

string

links

required

Links

docs always; billing, buy_pack, upgrade when they help.

object

key

additional properties

string

details

Details

meta

Any of:

Meta
null

Meta

object

data_as_of

required

Any of:

string
null

string

source

required

Any of:

string
null

string

mode

required

Any of:

string
null

string

Allowed values: live test

build_id

Any of:

string
null

string

request_id

Any of:

string
null

string

Example

{
  "error": {
    "code": "quota_exceeded"
  },
  "meta": {
    "mode": "live"
  }
}

429

Monthly quota, call packs and overage cap used up (quota_exceeded).

application/json

ErrorResponse

object

error

required

ErrorBody

object

code

required

Code

Stable, machine-readable error code.

string

message

required

Message

string

links

required

Links

docs always; billing, buy_pack, upgrade when they help.

object

key

additional properties

string

details

Details

meta

Any of:

Meta
null

Meta

object

data_as_of

required

Any of:

string
null

string

source

required

Any of:

string
null

string

mode

required

Any of:

string
null

string

Allowed values: live test

build_id

Any of:

string
null

string

request_id

Any of:

string
null

string

Example

{
  "error": {
    "code": "quota_exceeded"
  },
  "meta": {
    "mode": "live"
  }
}