gribstream-com Grid coordinates API

openapi: 3.2.0
info:
  title: GribStream Grid coordinates API
  version: '2026-10-15'
  description: 'Public OpenAPI description for GribStream''s customer-facing forecast query and catalog APIs.


    This published contract documents:

    - `/api/v2/quota` for free token-scoped credit quota and status inspection

    - public catalog discovery endpoints under `/api/v2/catalog/...`

    - `/api/v2/{dataset}/timeseries`

    - `/api/v2/{dataset}/runs`

    - `/api/v2/{dataset}/native-coordinates` for datasets with verified fixed-grid geometry

    - their legacy aliases `/history` and `/forecasts`


    Query responses support:

    - `text/csv` by default

    - `application/json` for a streamed JSON array

    - `application/ndjson` or `application/x-ndjson` for newline-delimited JSON

    - `application/vnd.apache.parquet` for typed, compressed binary results


    POST query endpoints can also return a short-lived signed URL for a CSV, JSON, NDJSON, or

    Parquet artifact by using `?delivery=url&format={format}` with `Accept: application/json`.

    The request body is unchanged.


    Timestamp conventions:

    - all request timestamps are UTC ISO 8601 datetimes

    - all response timestamps are UTC ISO 8601 datetimes


    Current handler behavior documented here:

    - `minLeadTime` / `maxLeadTime` override deprecated integer `minHorizon` / `maxHorizon`

    - on ensemble datasets, omitting `members` returns only the first member

    - deterministic datasets reject explicit `members` filters with `400 Bad Request`'
servers:
- url: https://gribstream.com
  description: Current deployment base URL
security:
- bearerAuth: []
tags:
- name: Grid coordinates
  description: Authenticated, metered native coordinate inventories.
paths:
  /api/v2/{dataset}/native-coordinates:
    get:
      tags:
      - Grid coordinates
      summary: Get exact native grid cell centers
      description: 'Streams native cell centers inside a required inclusive geographic bounding box.

        All four bounds are mandatory. Longitude may use -180..180 or 0..360;

        decreasing bounds wrap. CSV is default; JSON, JSON Lines and Parquet are supported.

        Satellite images include pixels that look past Earth. Only pixels with a

        geographic location are returned. AICON uses sub-metre quantized coordinates

        (less than 0.5 m error). Copy returned lat/lon into a weather request to choose

        locations from the native grid. There is no pagination.

        JSON returns a streamed array of lat/lon objects, like weather-query arrays.

        The weather-query delivery=url option is not supported here.


        Every request accounts for one credit per 500 returned coordinates, rounded up;

        empty boxes cost zero. There are no free downloads. No remaining quota returns

        429 with Retry-After before streaming. Admitted requests stream in one pass and

        stop after crossing quota, with at most one additional credit/500 points per

        request. CSV and JSON Lines stop cleanly, JSON closes correctly, and Parquet

        finalizes its footer. Streamed partial responses remain HTTP 200.


        Every format contains only lat/lon rows. JSON is a streamed array;

        Parquet has two DOUBLE columns and no custom grid or response-stat metadata.

        Grid specifications are available from the free catalog dataset detail endpoint.

        Quota-stopped streams remain valid but have no completion flag or response stats.

        Missing/unavailable remote geometry returns 503 before streaming when detected

        during source opening. Geometry inventory does not guarantee weather-value

        availability for a specific parameter or time.'
      operationId: getDatasetNativeCoordinates
      parameters:
      - $ref: '#/components/parameters/DatasetCodePath'
      - $ref: '#/components/parameters/AcceptHeaderNativeCoordinates'
      - name: minLat
        in: query
        required: true
        description: Southern latitude bound. Supply all four bounds together.
        schema:
          type: number
          format: double
          minimum: -90
          maximum: 90
      - name: maxLat
        in: query
        required: true
        description: Northern latitude bound.
        schema:
          type: number
          format: double
          minimum: -90
          maximum: 90
      - name: minLon
        in: query
        required: true
        description: Western longitude bound, between -180 and 360.
        schema:
          type: number
          format: double
          minimum: -180
          maximum: 360
      - name: maxLon
        in: query
        required: true
        description: Eastern longitude bound, between -180 and 360. A value below minLon wraps through the input convention's boundary.
        schema:
          type: number
          format: double
          minimum: -180
          maximum: 360
      responses:
        '200':
          description: Native coordinate inventory inside the requested bounding box.
          content:
            text/csv:
              schema:
                type: string
              example: 'lat,lon

                90,0

                '
            application/json:
              schema:
                $ref: '#/components/schemas/NativeCoordinateArray'
            application/ndjson:
              schema:
                type: string
              example: '{"lat":90,"lon":0}

                '
            application/x-ndjson:
              schema:
                type: string
            application/vnd.apache.parquet:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequestText'
        '401':
          $ref: '#/components/responses/UnauthorizedBearer'
        '403':
          description: Native coordinate inventories require a registered token.
        '404':
          description: Unknown dataset.
        '429':
          $ref: '#/components/responses/TooManyRequestsText'
        '503':
          description: Native coordinate inventory is temporarily unavailable.
        '501':
          description: Exact native grid coordinates are unavailable for this dataset.
components:
  parameters:
    DatasetCodePath:
      name: dataset
      in: path
      required: true
      description: Weather model code.
      schema:
        type: string
        enum:
        - aicon
        - aifsenfo
        - aifsoper
        - aigefspres
        - aigefssfc
        - aigfspres
        - aigfssfc
        - aiwpfourcastnet
        - aiwpfourcastnetifs
        - aiwpgraphcast
        - aiwpgraphcastifs
        - aiwppangu
        - aiwppanguifs
        - aqm
        - aqmak
        - aqmhi
        - aromefrance
        - barrac2
        - barrar2
        - camsglobal
        - ccpa1hndgd25
        - cdas
        - cfsflxf
        - cfsipvf
        - cfsocnf
        - cfspgbf
        - cwawrf15
        - dafsgtg
        - dafsifiak
        - dafsificonus
        - dmidini
        - era5
        - fourcastnetgfs
        - gdas
        - gefsatmos
        - gefsatmosmean
        - gefschem
        - gefsct
        - gefswaveprob
        - gfs
        - gmgsi
        - goes18abi
        - goes18abi10km
        - goes19abi
        - goes19abi10km
        - graphcast
        - grefs
        - gtgn
        - hrrr
        - hrrrsubh
        - icon2i
        - icon2iruc
        - iconarteu
        - icond2
        - iconeu
        - ifsenfo
        - ifsenfo0p1
        - ifsenfomean0p1
        - ifsenfoprob0p1
        - ifsenfospread0p1
        - ifsoper
        - ifsoper0p1
        - ifswaef
        - ifswaef0p1
        - ifswaefprob0p1
        - ifswave
        - ifswave0p1
        - metofficeglobal10km
        - metofficemogrepsg
        - metofficemogrepsuk
        - metofficeukv
        - mrms
        - mrmsazshear
        - namawip12
        - namawphys
        - namconusnest
        - namgoes218
        - nbm
        - nbmak
        - nbmgu
        - nbmhi
        - nbmoc
        - nbmpar
        - nbmparak
        - nbmpargu
        - nbmparhi
        - nbmparoc
        - nbmparpr
        - nbmparqmd
        - nbmpr
        - nbmqmd
        - nwmmediumlandens
        - nwmshortland
        - rap
        - refs2dfld
        - refsct
        - refsprslev
        - rrfs2dfld
        - rrfsprslev
        - rtma
        - rtmaru
        - smnwrf
        - spchail4hr
        - spcltg4hr
        - spctor4hr
        - spctstm1hr
        - spctstm4hr
        - spcwind4hr
        - urma
        - uvi
      example: gfs
    AcceptHeaderNativeCoordinates:
      name: Accept
      in: header
      required: false
      description: 'Defaults to `text/csv`. Use `application/json`, `application/ndjson`,

        `application/x-ndjson`, or `application/vnd.apache.parquet` to choose

        another format. The aliases `application/x-parquet` and `application/parquet`

        are normalized to `application/vnd.apache.parquet`. Parquet uses built-in

        Zstandard compression.

        Any other media type falls back to CSV.

        '
      schema:
        type: string
      example: application/vnd.apache.parquet
  responses:
    BadRequestText:
      description: Request validation failed.
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/TextMessage'
    UnauthorizedBearer:
      description: Missing, invalid, unknown, inactive, expired, or deleted bearer token.
      headers:
        WWW-Authenticate:
          $ref: '#/components/headers/WWWAuthenticateBearer'
    TooManyRequestsText:
      description: Quota exceeded, inventory rate limit reached, or demo-token abuse protection triggered.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfterSeconds'
      content:
        text/plain:
          schema:
            $ref: '#/components/schemas/TextMessage'
          examples:
            quotaExceeded:
              summary: Quota exceeded
              value: 'Out of quota. Retry-After: 43120'
            demoProtection:
              summary: Demo-token abuse protection
              value: 'Hello friend! This api token is for demo purposes. To continue usage please login and create a private API token at: https://gribstream.com/auth/login Cheers'
  headers:
    RetryAfterSeconds:
      description: Seconds until the next quota window when quota is exhausted.
      schema:
        type: string
        example: '43120'
    WWWAuthenticateBearer:
      description: Bearer challenge describing why auth failed.
      schema:
        type: string
        example: Bearer realm="gribstream", error="invalid_token", error_description="invalid API token"
  schemas:
    NativeCoordinateArray:
      type: array
      description: Native cell-center coordinates inside the requested box. No identifiers, geometry descriptors or response statistics are included.
      items:
        $ref: '#/components/schemas/NativeCoordinate'
    TextMessage:
      type: string
    NativeCoordinate:
      type: object
      required:
      - lat
      - lon
      properties:
        lat:
          type: number
          format: double
        lon:
          type: number
          format: double
          description: Longitude in the native grid convention, described in the catalog.
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API token
      description: 'Send your GribStream API token as:


        `Authorization: Bearer YOUR_TOKEN`

        '