Zone Analytics
The endpoint
| Endpoint | Answers |
|---|---|
GET /v1/analytics/zones/{id_type}/{id}/entries-exits | How many vessels entered and left over this period, broken down how I asked? |
This endpoint sits behind a base path of its own
/maritime-analytics. Call it at https://api.polestar-production.com/maritime-analytics/v1/analytics/zones/id/{id}/entries-exits. The reference page shows the path the service sees, without that prefix, because every other Insights endpoint carries its service prefix in the path itself and this one carries it in the base URL.Addressing a zone
{id_type}/{id}, and id_type has exactly one legal value: id, followed by the zone UUID. Ports accept a UN/LOCODE as a second form of identifier; zones have no equivalent, so the discriminator has nothing to discriminate between.GET /zone-port-insights/v1/zones, the same identifier every other zone endpoint takes. Custom zones work here too, so you can baseline activity in an area you drew yourself.Choosing the shape of the response
group_by and period_aggregation are both required, and the combination you pick decides what comes back. There are three useful ones:group_by | period_aggregation | What you get | Chart it as |
|---|---|---|---|
NONE | DAILY, WEEKLY, MONTHLY, QUARTERLY or YEARLY | One data point per period, each holding a single combined entry and exit count | A line over time |
VESSEL_TYPE | any period (any of DAILY, WEEKLY, MONTHLY, QUARTERLY or YEARLY, excluding NONE) | One data point per period, each holding one item per vessel type | A stacked or clustered bar |
VESSEL_TYPE | NONE | A single data point holding one item per vessel type, summed across the whole range | A donut or a pie |
NONE and NONE together is not a useful pair and not a shape worth asking for.group_by is NONE, every items array holds exactly one element, with group_by_key set to "none". Vessel types with nothing in a period are left out of that period rather than returned as zero, so do not rely on a fixed number of items per bucket.The period key is the end of the period, not the start
period_key is always the last calendar day of its bucket: the Sunday that closes a week, the last day of a month or quarter. It stays the end of the full period even when your date_end falls part way through one, so a chart axis built from it will not shift as you extend the range.Narrowing the traffic
vessel_types, ship type level-3 names such as Chemical Tanker or Bulk Carriervessel_class, size and capability classes within a typeflag_codes, ISO 3166-1 alpha-2 codes such as NO or GBtop_visitors_limit and top_visitors_sort, which shape the top_visitors array rather than the countstotals object reflects the whole range after every filter has been applied, so it agrees with the data array rather than describing the unfiltered zone.Vessel type coverage
What comes back
data and totals, the response carries zone_information with the zone's name, type and sub-type, and top_visitors: the vessels crossing the boundary most often over the range, with identity, flag, ship type and visit count. top_visitors is ten entries by default, up to 50, sorted busiest first unless you ask for ASC.Entries and exits, or the crossings themselves
zone-and-port-traffic and this endpoint answer the same question at different resolutions.| Returns | Use when | |
|---|---|---|
GET /zone-port-insights/v1/zone-and-port-traffic/{id_type}/{id} | Every ZONE_ENTRY and ZONE_EXIT event, one row per crossing | You need the crossings themselves: a timeline, an audit trail, a per-vessel history |
GET /v1/analytics/zones/{id_type}/{id}/entries-exits | Counts of those crossings, bucketed and grouped | You need volume: a trend, a distribution, a comparison between periods |
Date range
date_start and date_end are required, inclusive, and yyyy-MM-dd. The range may not span more than two years. We treat a date_end in the future as today (UTC).Related
Modified at 2026-10-16 05:45:58