@gojinko/api-client 2.19.1 → 2.21.0

package/public-api.yaml

@@ -1570,9 +1570,6 @@ components:
           type: string
         last_name:
           type: string
-    AnalysisType:
-      type: string
-      enum: [snapshot, trend]
     TravelPeriod:
       type: string
       enum: [Summer, Winter, Christmas, Easter, Next30Days, Next90Days, Custom]
@@ -1593,10 +1590,6 @@ components:
         share:
           type: number
           format: double
-        growth:
-          type: number
-          format: double
-          description: "Growth % in trend mode (analysis=trend); omitted in snapshot."
     MarketRow:
       type: object
       required: [market]
@@ -1608,10 +1601,6 @@ components:
         share:
           type: number
           format: double
-        growth:
-          type: number
-          format: double
-          description: "Growth % in trend mode (analysis=trend); omitted in snapshot."
     AudienceRow:
       type: object
       required: [audience]
@@ -1623,48 +1612,117 @@ components:
         share:
           type: number
           format: double
-        growth:
-          type: number
-          format: double
-          description: "Growth % in trend mode (analysis=trend); omitted in snapshot."
     DestinationResponse:
       type: object
-      required: [analysis_type, rows]
+      required: [rows]
       properties:
-        analysis_type:
-          $ref: "#/components/schemas/AnalysisType"
         rows:
           type: array
           items:
             $ref: "#/components/schemas/DestinationRow"
     MarketResponse:
       type: object
-      required: [analysis_type, rows]
+      required: [rows]
       properties:
-        analysis_type:
-          $ref: "#/components/schemas/AnalysisType"
         rows:
           type: array
           items:
             $ref: "#/components/schemas/MarketRow"
     AudienceResponse:
       type: object
-      required: [analysis_type, rows]
+      required: [rows]
       properties:
-        analysis_type:
-          $ref: "#/components/schemas/AnalysisType"
         rows:
           type: array
           items:
             $ref: "#/components/schemas/AudienceRow"
+    Granularity:
+      type: string
+      enum: [day, week, month]
+      description: "Bucket size for a trend series: week (default), day, or month."
+    TrendPoint:
+      type: object
+      required: [date, value]
+      properties:
+        date:
+          type: string
+          format: date
+          description: "Bucket start date (YYYY-MM-DD)."
+          example: "2026-06-20"
+        value:
+          type: number
+          format: double
+          description: De-sampled search volume for the bucket.
+          example: 1234
+    SeriesSummary:
+      type: object
+      description: Per-series rollup over the returned window.
+      properties:
+        total:
+          type: number
+          format: double
+          example: 34567
+        avg_per_day:
+          type: number
+          format: double
+          example: 1191
+        growth_pct:
+          type: number
+          format: double
+          nullable: true
+          description: "Within-window growth %: recent half vs. prior half. Null when the prior half is empty."
+          example: 12.3
+        peak_date:
+          type: string
+          format: date
+          example: "2026-06-14"
+        peak_value:
+          type: number
+          format: double
+          example: 1890
+    TrendSeries:
+      type: object
+      required: [series]
+      properties:
+        label:
+          type: string
+          description: "Ranked dimension value (destination/market/audience endpoints); omitted for the pairs endpoint."
+          example: "Country:FR"
+        origin:
+          type: string
+          description: "Pairs endpoint only: the origin selector for this series."
+          example: "Country:US"
+        destination:
+          type: string
+          description: "Pairs endpoint only: the destination selector for this series."
+          example: "Country:FR"
+        series:
+          type: array
+          items:
+            $ref: "#/components/schemas/TrendPoint"
+        summary:
+          $ref: "#/components/schemas/SeriesSummary"
+    TrendResponse:
+      type: object
+      required: [granularity, from, to, series]
+      properties:
+        granularity:
+          $ref: "#/components/schemas/Granularity"
+        from:
+          type: string
+          format: date
+          description: First (inclusive) bucket date of the window.
+          example: "2026-06-19"
+        to:
+          type: string
+          format: date
+          description: Last (inclusive) bucket date of the window.
+          example: "2026-06-25"
+        series:
+          type: array
+          items:
+            $ref: "#/components/schemas/TrendSeries"
   parameters:
-    analysis:
-      name: analysis
-      in: query
-      required: true
-      description: Analysis mode. `trend` is accepted but currently returns snapshot-shaped data.
-      schema:
-        $ref: "#/components/schemas/AnalysisType"
     originMarket:
       name: origin_market
       in: query
@@ -1759,30 +1817,62 @@ components:
       name: snapshot_window_days
       in: query
       required: false
-      description: "Snapshot mode only: number of most-recent days of search activity aggregated into the demand level (min 2, default 7, max 90 — a 1-day window is the current day, whose data is incomplete; the cube retains 90 days). Rejected when analysis=trend."
+      description: "Number of most-recent days of search activity aggregated into the demand level (min 2, default 7, max 90 — a 1-day window is the current day, whose data is incomplete; the cube retains 90 days)."
       schema:
         type: integer
         minimum: 2
         maximum: 90
-    trendWindowDays:
-      name: trend_window_days
+    limit:
+      name: limit
       in: query
       required: false
-      description: "Trend mode only: size in days of each of the two adjacent windows compared for growth (min 2, default 7, max 45 — a 1-day window's recent period is the current day, whose data is incomplete; a trend spans 2x the window within the cube's 90-day retention). Rejected when analysis=snapshot."
+      description: Max rows (1-200, default 20).
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 200
+        default: 20
+    origins:
+      name: origins
+      in: query
+      required: true
+      description: "Pairs endpoint: comma-separated origin selectors `<Level>:<Code>` (e.g. `Country:US,Country:CA`). v1: at most one of origins/destinations may have more than one entry."
+      schema:
+        type: string
+        minLength: 1
+    destinations:
+      name: destinations
+      in: query
+      required: true
+      description: "Pairs endpoint: comma-separated destination selectors `<Level>:<Code>` (e.g. `Country:FR,Country:DE`)."
+      schema:
+        type: string
+        minLength: 1
+    trendWindow:
+      name: trend_window
+      in: query
+      required: false
+      description: "Number of buckets N in the chosen granularity's own unit (min 2; max depends on granularity: day <= 60, week <= 52, month <= 12; default 12 applied server-side). The series spans the last N complete buckets, excluding the in-progress one."
       schema:
         type: integer
         minimum: 2
-        maximum: 45
-    limit:
+    granularity:
+      name: granularity
+      in: query
+      required: false
+      description: "Bucket size for the returned series: week (default), day, or month."
+      schema:
+        $ref: "#/components/schemas/Granularity"
+    trendLimit:
       name: limit
       in: query
       required: false
-      description: Max rows (1-200, default 20).
+      description: "Trend endpoints: maximum number of series (top-N keys). Default 10, max 50."
       schema:
         type: integer
         minimum: 1
-        maximum: 200
-        default: 20
+        maximum: 50
+        default: 10
 paths:
   /v1/destination:
     get:
@@ -1796,7 +1886,6 @@ paths:
         - ApiKeyAuth: []
         - BearerAuth: []
       parameters:
-        - $ref: "#/components/parameters/analysis"
         - $ref: "#/components/parameters/originMarket"
         - $ref: "#/components/parameters/destinationFilter"
         - $ref: "#/components/parameters/travelPeriod"
@@ -1809,7 +1898,6 @@ paths:
         - $ref: "#/components/parameters/searchWindowMin"
         - $ref: "#/components/parameters/searchWindowMax"
         - $ref: "#/components/parameters/snapshotWindowDays"
-        - $ref: "#/components/parameters/trendWindowDays"
         - $ref: "#/components/parameters/limit"
       responses:
         "200":
@@ -1840,7 +1928,6 @@ paths:
         - ApiKeyAuth: []
         - BearerAuth: []
       parameters:
-        - $ref: "#/components/parameters/analysis"
         - $ref: "#/components/parameters/destinationRequired"
         - $ref: "#/components/parameters/originMarket"
         - $ref: "#/components/parameters/travelPeriod"
@@ -1853,7 +1940,6 @@ paths:
         - $ref: "#/components/parameters/searchWindowMin"
         - $ref: "#/components/parameters/searchWindowMax"
         - $ref: "#/components/parameters/snapshotWindowDays"
-        - $ref: "#/components/parameters/trendWindowDays"
         - $ref: "#/components/parameters/limit"
       responses:
         "200":
@@ -1886,7 +1972,6 @@ paths:
         - ApiKeyAuth: []
         - BearerAuth: []
       parameters:
-        - $ref: "#/components/parameters/analysis"
         - $ref: "#/components/parameters/destinationRequired"
         - $ref: "#/components/parameters/originMarket"
         - $ref: "#/components/parameters/travelPeriod"
@@ -1898,7 +1983,6 @@ paths:
         - $ref: "#/components/parameters/searchWindowMin"
         - $ref: "#/components/parameters/searchWindowMax"
         - $ref: "#/components/parameters/snapshotWindowDays"
-        - $ref: "#/components/parameters/trendWindowDays"
         - $ref: "#/components/parameters/limit"
       responses:
         "200":
@@ -1919,6 +2003,186 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
+  /v1/trend:
+    get:
+      tags:
+        - demand
+      summary: Demand time series for explicit origin/destination pairs
+      description: >-
+        Deep dive: returns one de-sampled search-volume series per
+        (origin, destination) pair. v1 allows a list on only one side — a single
+        origin with many destinations, or many origins with a single destination.
+      security:
+        - ApiKeyAuth: []
+        - BearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/origins"
+        - $ref: "#/components/parameters/destinations"
+        - $ref: "#/components/parameters/travelPeriod"
+        - $ref: "#/components/parameters/departureDateFrom"
+        - $ref: "#/components/parameters/departureDateTo"
+        - $ref: "#/components/parameters/travelerType"
+        - $ref: "#/components/parameters/tripType"
+        - $ref: "#/components/parameters/tripDurationMin"
+        - $ref: "#/components/parameters/tripDurationMax"
+        - $ref: "#/components/parameters/searchWindowMin"
+        - $ref: "#/components/parameters/searchWindowMax"
+        - $ref: "#/components/parameters/trendWindow"
+        - $ref: "#/components/parameters/granularity"
+      responses:
+        "200":
+          description: Per-pair demand time series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TrendResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/destination/trend:
+    get:
+      tags:
+        - demand
+      summary: Demand time series for the top-N destinations
+      description: >-
+        Ranks destinations (optionally reachable from origin_market) by
+        within-window growth, then returns each top-N destination's series.
+      security:
+        - ApiKeyAuth: []
+        - BearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/originMarket"
+        - $ref: "#/components/parameters/destinationFilter"
+        - $ref: "#/components/parameters/travelPeriod"
+        - $ref: "#/components/parameters/departureDateFrom"
+        - $ref: "#/components/parameters/departureDateTo"
+        - $ref: "#/components/parameters/travelerType"
+        - $ref: "#/components/parameters/tripType"
+        - $ref: "#/components/parameters/tripDurationMin"
+        - $ref: "#/components/parameters/tripDurationMax"
+        - $ref: "#/components/parameters/searchWindowMin"
+        - $ref: "#/components/parameters/searchWindowMax"
+        - $ref: "#/components/parameters/trendWindow"
+        - $ref: "#/components/parameters/granularity"
+        - $ref: "#/components/parameters/trendLimit"
+      responses:
+        "200":
+          description: Top-N destination time series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TrendResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/market/trend:
+    get:
+      tags:
+        - demand
+      summary: Demand time series for the top-N source markets
+      description: >-
+        Ranks source markets for a destination by within-window growth, then
+        returns each top-N market's series. `destination` is required.
+      security:
+        - ApiKeyAuth: []
+        - BearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/destinationRequired"
+        - $ref: "#/components/parameters/originMarket"
+        - $ref: "#/components/parameters/travelPeriod"
+        - $ref: "#/components/parameters/departureDateFrom"
+        - $ref: "#/components/parameters/departureDateTo"
+        - $ref: "#/components/parameters/travelerType"
+        - $ref: "#/components/parameters/tripType"
+        - $ref: "#/components/parameters/tripDurationMin"
+        - $ref: "#/components/parameters/tripDurationMax"
+        - $ref: "#/components/parameters/searchWindowMin"
+        - $ref: "#/components/parameters/searchWindowMax"
+        - $ref: "#/components/parameters/trendWindow"
+        - $ref: "#/components/parameters/granularity"
+        - $ref: "#/components/parameters/trendLimit"
+      responses:
+        "200":
+          description: Top-N market time series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TrendResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+  /v1/audience/trend:
+    get:
+      tags:
+        - demand
+      summary: Demand time series for the traveler-type mix
+      description: >-
+        Returns a series per traveler-type segment (Solo / Couple / Family /
+        Group) of demand for a destination. `destination` is required;
+        `traveler_type` is not a filter here — this endpoint buckets by it.
+      security:
+        - ApiKeyAuth: []
+        - BearerAuth: []
+      parameters:
+        - $ref: "#/components/parameters/destinationRequired"
+        - $ref: "#/components/parameters/originMarket"
+        - $ref: "#/components/parameters/travelPeriod"
+        - $ref: "#/components/parameters/departureDateFrom"
+        - $ref: "#/components/parameters/departureDateTo"
+        - $ref: "#/components/parameters/tripType"
+        - $ref: "#/components/parameters/tripDurationMin"
+        - $ref: "#/components/parameters/tripDurationMax"
+        - $ref: "#/components/parameters/searchWindowMin"
+        - $ref: "#/components/parameters/searchWindowMax"
+        - $ref: "#/components/parameters/trendWindow"
+        - $ref: "#/components/parameters/granularity"
+        - $ref: "#/components/parameters/trendLimit"
+      responses:
+        "200":
+          description: Per-segment time series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TrendResponse"
+        "401":
+          description: Authentication required
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "422":
+          description: Validation error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
   /health:
     get:
       tags: