@gojinko/api-client 2.19.0 → 2.20.0

package/public-api.yaml

@@ -1657,6 +1657,92 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/AudienceRow"
+    Granularity:
+      type: string
+      enum: [day, week, month]
+      description: "Bucket size for an evolution series: day (default), week, or month."
+    EvolutionPoint:
+      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
+    EvolutionSeries:
+      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/EvolutionPoint"
+        summary:
+          $ref: "#/components/schemas/SeriesSummary"
+    EvolutionResponse:
+      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/EvolutionSeries"
   parameters:
     analysis:
       name: analysis
@@ -1759,19 +1845,19 @@ 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 (default 7, max 90 — the cube retains 90 days). Rejected when analysis=trend."
+      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."
       schema:
         type: integer
-        minimum: 1
+        minimum: 2
         maximum: 90
     trendWindowDays:
       name: trend_window_days
       in: query
       required: false
-      description: "Trend mode only: size in days of each of the two adjacent windows compared for growth (default 7, max 45 — a trend spans 2x the window within the cube's 90-day retention). Rejected when analysis=snapshot."
+      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."
       schema:
         type: integer
-        minimum: 1
+        minimum: 2
         maximum: 45
     limit:
       name: limit
@@ -1783,6 +1869,48 @@ components:
         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
+    evolutionWindowDays:
+      name: trend_window_days
+      in: query
+      required: false
+      description: "Size of the evolution window in days (min 2, default 7, max 45). The series spans the last N complete days ending yesterday; the current day is excluded as incomplete."
+      schema:
+        type: integer
+        minimum: 2
+        maximum: 45
+    granularity:
+      name: granularity
+      in: query
+      required: false
+      description: "Bucket size for the returned series: day (default), week, or month."
+      schema:
+        $ref: "#/components/schemas/Granularity"
+    evolutionLimit:
+      name: limit
+      in: query
+      required: false
+      description: "Evolution endpoints: maximum number of series (top-N keys). Default 10, max 50."
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 50
+        default: 10
 paths:
   /v1/destination:
     get:
@@ -1919,6 +2047,186 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
+  /v1/evolution:
+    get:
+      tags:
+        - demand
+      summary: Daily demand time series for explicit origin/destination pairs
+      description: >-
+        Deep dive: returns one daily 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/evolutionWindowDays"
+        - $ref: "#/components/parameters/granularity"
+      responses:
+        "200":
+          description: Per-pair demand time series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvolutionResponse"
+        "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/evolution:
+    get:
+      tags:
+        - demand
+      summary: Daily 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 daily 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/evolutionWindowDays"
+        - $ref: "#/components/parameters/granularity"
+        - $ref: "#/components/parameters/evolutionLimit"
+      responses:
+        "200":
+          description: Top-N destination time series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvolutionResponse"
+        "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/evolution:
+    get:
+      tags:
+        - demand
+      summary: Daily 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 daily 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/evolutionWindowDays"
+        - $ref: "#/components/parameters/granularity"
+        - $ref: "#/components/parameters/evolutionLimit"
+      responses:
+        "200":
+          description: Top-N market time series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvolutionResponse"
+        "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/evolution:
+    get:
+      tags:
+        - demand
+      summary: Daily demand time series for the traveler-type mix
+      description: >-
+        Returns a daily 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/evolutionWindowDays"
+        - $ref: "#/components/parameters/granularity"
+        - $ref: "#/components/parameters/evolutionLimit"
+      responses:
+        "200":
+          description: Per-segment time series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvolutionResponse"
+        "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: