Home page 
Home Your Room Login Contact Feedback Site Map Search:  
Discover this product 
About Us
Getting here
Order Data
Order Software
Open Tenders
Home > Products > Data Services > Software >Grib API > Grib API changes  

GRIB API - History of changes


January 2013 version 1.10.0

  • Updated copyright notices to Apache Licence Version 2.0
  • Availability of grib2netcdf tool from grib_api
  • Support in grib_api for Lambert Conformal grid (grib_get_data)
  • Updated GRIB edition 2 definitions with the latest WMO V9 templates/tables
  • ERA-CLIM: Added support for Simulated Radiances
  • LWDA: Added support to Long Window 4DVar
  • ERA-CLIM: New stream (ensemble supplementary data) and origin (Hadley Centre)
  • GRIB definitions of new variables from LISFLOOD hydrological model
  • Added Local Definition 21 (Sensitive area predictions) for GRIB edition 2
  • Provided user-friendly function in API to check if a key is defined (grib_is_defined)
  • Python: Provided function to set key values in one go (like grib_set -s)
  • New MARS codes for surface parameters (effective total cloudiness)
  • Corrected ifs_samples installation path
  • New streams for ensemble data added to the parameter database
  • New mars streams added for ensemble data assimilation
  • Added pseudo-grib (budg) sample file for IFS
  • Added new centre codes for COSMO, Ireland and Austria
  • Bug fix: python interface missing __version__
  • Bug fix: on make dist, definitions and sample go to /usr/share instead of /usr/share/grib_api/
  • Bug fix: padding.sh fails in Debian automatic build machines
  • Bug fix: Lambert azimuthal equal area
  • Bug fix: Assertion when trying to encode the level information of some cloud cover fields
  • Bug fix: ERA-CLIM: Support for existing streams EDMM, EDMO, EWMM, EWMO
  • Bug fix: Netcdfs generated by grib_to_netcdf seem to be upside down
  • Bug fix: python binding without numpy support grib_get_array(gid,'pv',float)
  • Bug fix: grib_dump crashing with some second order packed files
  • Bug fix: running grib_to_netcdf on a non regular lat/lon grid grib file results in invalid netcdf
  • Bug fix: Assertion: Interpolation (or truncation) of GRIB 2 data into T21
  • Bug fix: Make sure that grib_filter checks all disk writes.
  • Bug fix: if "configure" is run without --prefix, IFS_SAMPLES_PATH starts with "NONE"
  • Bug fix: grib_to_netcdf: long_name/units incorrect
  • Bug fix: grib_filter error: converting edition 1 to 2: unable to get extraDimensionPresent as long
  • Bug fix: grib_check Fortran definition is inconsistent with other Fortran definition:
    uses "integer" instead of "integer(kind=kindOfInt)" as status variable
  • Bug fix: Remove redundant MARS type and stream entries for TIGGE
  • Bug fix: Remove layer information from grib_api concepts for soil parameters
  • Bug fix: grib_api 1.10.0 with MARS client: Interpolation failed
  • Bug fix: Remove parameter 500011: 2m Temperature
  • Bug fix: Remove new grib2 representations for parameters: 210004 and 210061
  • Bug fix: Wrong short name for centre 82 in 0.table
  • Bug fix: configure option disable-vector actually enables it!
  • Bug fix: LWDA: Support for Errors in Analysis

October 2012 version 1.9.18

  • Updated sample gribs with recent changes for Reduced Gaussian N1024 and N2000
  • Updated GRIB2 definitions with the latest WMO version 8 templates/tables
  • Added missing parts in Grid Definition Template 3.120
  • Added GRIB2 template 4.32 (simulated satellite data)
  • Removed redundant MARS files for type and stream combinations
  • Bug fix: Segmentation violation: calling grib_set on 'values' (decimal scale factor)
  • Bug fix: grib_get_data returns incorrect lat-lon values for some GRIBS
  • Bug fix: grib_filter does not fail with a non-zero return code when setting an invalid key
  • Bug fix: Cannot set paramId to 228170 (Field Capacity) for grib edition 2
  • Bug fix: grib_api compilation fails when enabling pthreads in recent Linux distributions
  • Bug fix: Segmentation violation when GRIB_DEFINITION_PATH contains colon
  • Bug fix: Compilation failure: problems with GRIB_INLINE: undefined reference to stdio_read etc
  • Bug fix: Setting step to the new value in GRIB2 creates wrong [day,hour]endOfOverallTimeInterval
  • Bug fix: grib_keys -L should show the real contents of SAMPLES PATH
  • Bug fix: Crash: Running the fortran example get_data
  • Bug fix: grib_filter with verbose option -v writes out lots of blank lines
  • Bug fix: tools/grib1to2.sh depends on /usr/bin/ksh which is a non standard location and breaks RPMs
  • Bug fix: GRIB1: Problem with derive probability for wave height larger than 8m
  • Bug fix: Bug when printing thickness of layers (typeOfLevel = depthBelowLandLayer)
  • Bug fix: Correct typos in parameter database
  • Bug fix: test script second_order.sh not working on some stricter shells
  • Bug fix: Compilation failure: tools/grib_compare.c - error on SX9 with the "end" variable
  • Bug fix: Build fails in Solaris 10: Wrong Fortran module include

March 2012 version 1.9.16

  • Disabled boustrophedonic ordering in second order packing.
  • Fixed the python bug in setting keys of type "double".
  • New parameters have been added to the parameter database and to the definition files.
  • Fixed a problem producing unwanted padding between messages when converting some fields from second order packing.
  • Improved thread safety in relation to the creation of an index. Creating a new grib_handle or indexing different files is thread safe.
  • Fixed grib_dump not to display zeros when all values were missing.
  • Fixed minor bugs.

March 2011 version 1.9.9

  • Two versions of the library are available for download. One is based on libtool and the other one has a build system similar to the previous versions. With the libtool version it is possible to build a shared or static library just changing the --enable-static, --enable-shared options of the configure script. The default behaviour is to generate the shared library.
  • Several changes have been made to the internal functions used by the interpolation package in EMOSLIB 381 to make the results of the grib_api based interpolation as close as possible to the GRIBEX based one.
  • New parameters have been added to the parameter database and to the definition files regarding the MACC project.
  • Second order packing (packingType=grid_second_order) is producing smaller fields as the default setting is to use the boustrophedonic option.
  • Installation of IFS samples files is made automatically in the directory ifs_samples under the installation path or can be configured to be in any directory with the configure option --with-ifs-samples="directory where to install IFS samples".
  • Fixed memory leaks in the python bindings.

February 2011 version 1.9.8

  • IMPORTANT CHANGE: A significant change in the Fortran interface has been made. As a consequence of this change, user programs that ran correctly with previous versions may exhibit memory allocation problems after linking with version 1.9.8 due to unreleased memory associated with the GRIB messages being processed. This change is necessary to avoid possible problems in programs using previous versions.

In previous versions (starting from version 1.6.1) the argument IGRIB of the functions GRIB_NEW_FROM_FILE, GRIB_NEW_FROM_MESSAGE, GRIB_NEW_FROM_SAMPLE, GRIB_NEW_FROM_INDEX, GRIB_CLONE was both an input and output argument. Memory was released when a value of IGRIB associated with a valid message was passed to the function. It has been realised that this behaviour is a possible source of unexpected results when the IGRIB variables used in user programs are not initialised to a non valid IGRIB value (zero or negative integer).

Starting from version 1.9.8, IGRIB is output only and the grib message associated with IGRIB will never be released by one of the functions above. This means that to deallocate the memory associated with the message a call to GRIB_RELEASE(IGRIB) must be introduced once that message is no longer needed. We strongly advise users to revise existing codes using previous grib_api versions or to link to the new library, add the appropriate calls to GRIB_RELEASE and test for memory allocation issues.

For convenience we report an example of code which could cause problems and needs to be reviewed by users of the library.

integer :: IGRIB1
integer :: IGRIB2

call grib_new_from_file(IGRIB1,...)
... do something ...
call grib_new_from_file(IGRIB2,...)
... do something ...

IGRIB1 and IGRIB2 are not initialised to zero and therefore it is not known which value is assigned to them. It could be IGRIB1=IGRIB2=5 or any other number greater than or equal to zero. If this happens, at the second call of grib_new_from_file IGRIB1 will be replaced by IGRIB2 leading to very dangerous consequences as IGRIB1 no longer points to the intended GRIB message. Please revise your code in view of this example or link to the new version and add a call to the GRIB_RELEASE function to deallocate the memory when it is no longer needed as it is not deallocated automatically in the new version.

  • Second order packing algorithm rewritten and working in GRIB edition 1 and 2 with
  • This version is ready to be used with the new GRIB edition 1 and 2 interpolation function (INTF2) available in EMOSLIB version 377.
  • The key longitudeOfSouthernPoleInDegrees has been changed in GRIB edition 2 to convert the negative longitude values in the 0-360 range because negative values of longitudes are not allowed in GRIB edition 2.
  • Review and update of the code tables.
  • Added new parameters. Full list of parameters accessible from
  • Bug fixes.

October 2010 version 1.9.5

  • Python interface available with the configure option --enable-python. See http://www.ecmwf.int/publications/manuals/grib_api/namespacegribapi.html
    and http://www.ecmwf.int/publications/manuals/grib_api/grib_examples.html
  • Available new environment variable GRIB_API_IO_BUFFER_SIZE defining the size in bytes of the buffer used in the IO calls from Fortran and in the tools.
  • Performance improvements and partial vectorisation for the NEC SX platform.
  • Review and update of the code tables.
  • Update of paramId, shortName, name key values and release of a new parameter database web interface.
  • Added a new key called 'global' for regular_gg and reduced_gg which can take the values 1 ( =True) or 0 (=False).
    This is used to specify whether the grid is global or not. Setting global=1 will set the grid parameters computed from N and Ni only. It is used in the conversion from one edition to the other.
  • Available new environment variable GRIB_API_NO_ABORT. Default value is 0 and when it is set to 1 the library will not abort on failing asserts.
  • Bug fixes.

May 2010 version 1.9.0

  • Setting paramId or converting from one edition to the other when a parameter is not
    defined in the paramId.def file will result in a failure.
  • Improved performance in reading/cloning a message.
  • Changed the indexing system and provided new functions to write the index on a file
    grib_index_write and read it grib_index_read.
  • Provided a new tool to build an index from a set of files: grib_index_build.
  • The tool grib_compare is able to compare two index files, running through the grib messages indexed in the first and searching for them in the second.
  • Definition files and library have been updated to be used in operational status in the
    IFS cycle 36R2
  • grib_ls has slightly changed format.
  • A -j option is provided in grib_ls (-l only) to have the output in json format.
  • BUFR messages are read, but only very basic decoding is provided.
  • Parameters have been updated.
  • Native type of paramId has been changed from string to integer.
  • Several small bug fixes.

July 2009 version 1.8.0

  • Improved conversion from edition 1 to 2. Set edition=2 will do the conversion from edition 1 to 2 also of the parameter information.
  • shortName, paramId and units are defined for all the official WMO parameters and for local parameters used at ECMWF and NCEP
  • Added two keys: libraryVersion, definitionFilesVersion.
  • grib_compare has been modified to compare grib 1 and 2 (option -e). Other important changes have been done on grib_compare (see examples ) to have a more powerful tool to compare headers and values. New options are provided to choose the tolerance and new namespaces are available to compare only the relevant part of information. The new namespaces are. parameter,geography,vertical,time,local,data.
  • Option -n has been added to grib_ls to list the value of the set of keys belonging to a given namespace. grib_ls -n time in.grib will print the same time information for grib edition 1 and 2.
  • For some ECMWF local definitions the conversion rules have been included in grib_api.
  • A new key cfName is provided for the netcdf CF name. It is at the moment defined only for some parameters.
  • The parameter information is generated from a parameter database maintained at ECMWF and accessible from a new section in the grib_api web pages.
  • A new key typeOfLevel valid for grib edition 1 and 2, with the following values has been introduced: 'surface', 'cloudBase', 'cloudTop', 'isothermZero', 'adiabaticCondensation', 'maxWind', 'tropopause', 'nominalTop', 'seaBottom', 'isobaricInhPa', 'isobaricInPa', 'isobaricLayer', 'meanSea', 'isobaricLayerHighPrecision', 'isobaricLayerMixedPrecision', 'heightAboveSea','heightAboveSeaLayer', 'heightAboveGroundHighPrecision', 'heightAboveGround', 'heightAboveGroundLayer', 'sigma', 'sigmaLayer', 'sigmaLayerHighPrecision', 'hybrid', 'hybridLayer', 'depthBelowLand', 'depthBelowLandLayer', 'theta', 'thetaLayer', 'pressureFromGround', 'pressureFromGroundLayer', 'potentialVorticity', 'depthBelowSea', 'entireAtmosphere', 'entireOcean', 'oceanWave', 'oceanMixedLayer'
  • The open source library OpenJpeg can be used in place of Jasper for the jpeg 2000 coding. --with-openjpeg options in the configure.
  • decimalPrecision can be used also with grid_jpeg packing.
  • parameterName,parameterUnits are provided from the code tables.
  • packingError is also available for spherical harmonics packing. It provides the error due to simple packing.
  • option -l added in grib_get
  • option -F added in grib_get and grib_ls to control the format of floating point keys.
  • grib_ls output has been changed due to the introduction of the new typeOfLevel key
  • Subroutine grib_is_missing added in the Fortran interface to check if a header value is missing.
  • Changed step behaviour. If the step is "instant" and the value doesn't fit into one byte (in grib 1) an appropriate value of timeRangeIndicator is found to code the value in two bytes instead of 1.
  • In grib_filter the function "append" has been added to append a message to a file as opposed to "write" which is writing from the beginning of the file.
  • A new grib_count function is available to count (very fast) the number of messages in a list of files.
  • The value of the key level is zero in both edition when it is not relevant for the message and it is missing in grib edition 2.
  • The indexing routines have been improved to process string keys.

March 2009 version 1.7.0

  • New indexing routines. Example: index.f90
  • New keys stepType,stepUnits,stepRange,startStep,endStep.
  • New keys swapScanningX, swapScanningY, swapScanningLat, swapScanningLon. To
    swap the field respect one axis. They swap data and fix the header accordingly.
  • "Improved" error messages.
  • write multi fields. Previous versions of grib_api were able only to read multi
    fields, now you can also write multi fields. We don't suggest to you this
    feature, it is included only to be compliant with FM-92 spec.
    Examples: multi.f90, multi_write.f90, multi.c, write_multi.c
  • function grib_new_from_template is deprecated and it will be replaced with
    grib_new_from_samples. Also the environment variable GRIB_TEMPLATES_PATH is
    replaced by GRIB_SAMPLES_PATH. Please replace "template" with "samples" in all
    the C functions also. The behavior is the same. I made a new example showing the
    best practice to use samples. The technique of cloning is strongly recommended.
    Example: samples.f90
  • New key decimalPrecision provided. Used in the previous example. Regarding
    decimalPrecision and bitsPerValue the following problem was found in the
    previous version. If after loading from file or from sample (template) or
    cloning a constant field you set some non constant values the library doesn't
    know the bitsPerValue or the decimalPrecision you want to code (those are zero
    in the constant field). The result could have been a field coded with a poor
    precision. Starting with the new 1.7.0 version in these ambiguous cases grib_api
    is using 24 bits to pack the field (safe value). We always suggest to set
    explicitly the bitsPerValue or decimalPrecision or to clone non constant fields
    with those values properly set.
  • grib_copy, grib_set. A key name in square brackets can be used in the output
    file name. The key will be replaced with its value in the processed grib
    message. This will provide an easy way for splitting fields as the file name
    will be dependent on some key values. Example:
    grib_copy input.grib "output_[shortName]_[date]_[step].grib"
    Please remember to quote the file name otherwise you can get strange behaviors
    due to the shell.
  • New key packingError. The error introduced by the packing algorithm is
    returned with this key. It is available only for some packing algorithms. All
    the packed values are affected by this error in the sense that
    original value before packing = unpacked value ± packingError
    packingError is different for different fields (also for different steps of the
    same parameter/level/run).
  • all the nearest functions are returning the distance from the grid point in
    Km, using the radius coded in the message.
  • key bitmapPresent now available also in grib 2. Example: set_bitmap.f90

September 2008 version 1.6.4

  • Fields containing a bitmap with all missing values can be coded in grib1 and grib2
  • Multifields grib2 messages can be loaded from memory.
  • local definition 31 added
  • Better use of memory
  • minor bug fixes

July 2008 version 1.6.1

  • More efficient use of memory and improvement of performance.
  • Thread safe version available through the --enable-pthread configure option.
  • New computation of kindOfInt, kindOfLong, kindOfDouble, kindOfFloat, kindOfSize to allow safe arguments handing between Fortran 90 and C.
  • A new key bitmap is provided to get the full bitmap as a string with the grib_filter instruction: print "[bitmap]";
  • all the tools are failing on error and can be forced to proceed execution with the option -f . The only exception is grib_ls because we already have an identical tool failing (grib_get).
  • new error messages from the Fortran 90 interface will give you some more chance to debug your code.
  • New function grib_count_in_file available from Fortran and C to count the messages in a file. See example: examples/F90/count_messages.f90
  • In the Fortran 90 interface any valid grib id passed to a grib_new_from_file or grib_new_from_message will be released before being assigned to a new grib message. Example
    call grib_new_from_file(ifile,igrib, iret)
    do while (iret /= GRIB_END_OF_FILE)
    ... do something with the message pointed by igrib
    ... igrib will have the same value, but
    ... it will point to a different message each cycle
    ... the message from the previous cycle will be released
    ... no need for grib_release(igrib)
    call grib_new_from_file(ifile,igrib, iret)
    If you want to keep the grib message in memory remember to pass a negative grib id. Example
    call grib_count_in_file(ifile,n)
    allocate (igrib(n))
    do i=1,n
    call grib_new_from_file(ifile,igrib(i), iret)
    ... remember to release the grib ids to free memory
    do i=1,n
    call grib_release(igrib(i))
  • grib_filter is now able to print with a format, number of colums and a separator for array keys. The format is expressed with a % followed by a C like (printf) format declarator. The number of columns is started with ! The separator string is delimited by ' ' Examples print "[values!6%.5f',']" values with 5 digits precision in 6 columns separated by , print "[latitudes%.3f!1]" latitudes with 3 digits precision in a column print "pl={[pl!7', ']}" pl (number of point for each latitude) in 7 columns separated by ', '
  • New keys: julianDay latLonValues array containing latitude(1),longitude(1),value(1), latitude(2),longitude(2),value(2),..., latitude(N),longitude(N),value(N) (N=number of points in the grid) latitudes latitude(1),latitude(2),...,latitude(N) (N=number of points in the grid) longitudes longitude(1),longitude(2),...,longitude(N) (N=number of points in the grid) distinctLatitudes list of distinct latitudes distinctLongitudes list of distinct longitudes
  • minor bug fixes

June 2008 version 1.5.0

  • Modified the internal retrieval of keys, improving performance in getting and setting keys.
  • Implemented memory management. An efficient tecnique to reuse memory is implemented. --disable-memory-management configure option available to disable the memory management and use system malloc/free.
  • Some experimental multithreaded packing is available for big endian machines. A configure option --enable-omp-packing is provided to enable the openMP instructions contained in the new packing. The environment variable OMP_NUM_THREADS sets the number of threads used in the packing algorithm.
  • grib_filter improvements:
    • it is now possible to set array keys like values or pl as follows:

    values = { 0.1, 3.2, 7.5 };

    • it is now possible to print array keys like values or pl as follows:

    print "values=[values]";

    it is also possible to print on a file ("test.out") doing:

    print("test.out") "values=[values]";

    • better error messages are printed
    • it does not fail if an undefined key is used in a write or print statement
  • New keys or changed keys:
    • a scale factor and an offset can be applied to the data values through the keys "scaleValuesBy" and "offsetValuesBy".
    • setBitsPerValue is the new key to be used to change the number of bits per value. It also executes the repacking.
    • The keys periodOfTime is now working also when indicatorOfUnitOfTimeRange=0 (time units is minutes)
  • Concepts can be defined by the user. Concepts are a way to link the value of a key to a combination of values of other keys. They are used to define the short_name and the name.
  • minor bug fixes

February 2008 version 1.4.0

  • New Fortan 90 interface. Main featues:
    • unique grib_get/grib_set subroutines to get/set any variable type.
    • status code is an optional argument in all the subroutines (when omitted the program will exit in case of error)
    • new subroutine grib_get_data to get the latitude/longitude/values arrays.
    • new subroutine grib_get_element to get one or several elements of an array key through their index.
    • new subroutine grib_nearest function to get the nearest grid point of a given lat/lon. It accepts in input also arrays of latitude/longitudes to find the nearest points in one single call. A land sea mask mode is also available to get the nearest land point.
  • New Fortran 90 examples and documentation.
  • New grib_keys tool to obtain the list of keys available for a specified type of grib.
  • Modified the -l option in grib_ls (see documentation or type grib_ls without arguments)
  • fixed a bug in the grib_filter and added the -o option for the output file.
  • minor bug fixes.

November 2007 version 1.3.0

  • grib_ls -l lat/lon/mode to retrieve values in the nearest grid points of a given latitude longitude point.
  • grib_ls -B"order by" to order the output using some keys.
  • grib_ls -i index. To extract the value in the index grid point.
  • new grib_dump exposing a minimum set of keys which are the ones suggested for the standard use. Some options added to the grib_dump. The output of this new grib_dump is ready to be coupled to the new grib_gen which will be released in the next version.
  • grib_copy -r to repack data fixing problems in the original file.
  • improved keys search for faster tools.
  • grib_get_data and grib_iterator working with all scanning mode.
  • new experimental functions introduced, not available in the fortran interface: grib_fieldset_new,grib_fieldset_apply_order_by,grib_fieldset_next_handle grib_nearest_new,grib_nearest_find,grib_nearest_delete.
  • some examples on the grib_fieldset and grib_nearest are added.
  • The management of the missing data in grib_get_data is changed. Please refer to the help obtained executing grib_get_data without arguments.
  • Added the key stepRange which is native type string. It can represent start and end of a cumulation or a max of min interval. Example stepRange=24-36 for a precipitation means that it is cumulated between 24 and 36. It also addresses the problems with the big steps which don't fit in the grib1 P1 and P2.
  • Added key numberOfCodedValues. It is different from numberOfValues only if a bitmap is present and the difference between the two should be numberOfMissingValues.
  • Added the option -g to grib_copy, grib_set, grib_convert, grib_filter to preserve GTS headers wrapping the grib message.
  • fixed some bugs in the fortran interface.
  • fixed a bug in reading the signed floats with the grib_convert.

September 2007 version 1.2.0

  • Changed licensing policy. Now grib_api is distributed under LGPL. See LICENSE and gpl-3.0.txt files in the distribution directory.
  • Changed io functions and configure.ac to support files larger than 2GB.
  • As a consequence to the large file support the key offset has native type double.
  • Added support for predefined grids.
  • Modified grib_handle_new_from_file to read messages with wrong message length. In this case an error will be raised.
  • A new -M option is provided for all the tools to turn off the multi-field grib
  • Changed behaviour of grib_copy. Default is quiet and option -v (verbose) is available.

July 2007 version 1.1.0

  • Fixed a bug affecting constant fields.
  • Rewritten the ibm floating point encoding/decoding routines gaining a factor of 7 in performance.
  • Fixed a problem in the configure affecting compilation of fortran programs on AIX platforms.
  • Added some new keys:
    - max,min,average (maximum, minimum and average respectively of the data )
    - numberOfDataPoints (alias numberOfPoints) computed from the grid description
    - numberOfValues is the same as the numberOfPoints if a bitmap is not present
    otherwise it takes into account the bitmap
    - numberOfMissing (alias numberOfMissingValues) number of missing values in the field.
    It's easy to check if a field is constant by simply comparing max,min,average
    and some information about bitmap and missing values can be found comparing numberOfValues, numberOfPoints, numberOfMissing.
  • Added some new tests.
  • Added a new example on how to print all the data when the iterator is not available.
  • grib_tools are now failing with an error when the input file does not contain any
    valid grib message.
  • Added management of reduced gaussian non global fields.


April 2007 version 1.0 first release version




Top of page 21.01.2013
  Page Details        © ECMWF