0
# Key-Value Access
1
2
Comprehensive API for reading and writing meteorological parameters, metadata, and configuration values from GRIB/BUFR messages. The key-value system enables access to all message properties using standardized key names with automatic type conversion and validation.
3
4
## Capabilities
5
6
### Generic Get Operations
7
8
Universal functions for retrieving values with automatic type detection.
9
10
```python { .api }
11
def codes_get(msgid, key, ktype=None):
12
"""
13
Get key value with automatic type detection.
14
15
Parameters:
16
- msgid (int): Message handle ID
17
- key (str): Key name (e.g., 'paramId', 'level', 'dataDate')
18
- ktype (int, optional): Force specific type conversion
19
20
Returns:
21
int|float|str: Key value in appropriate Python type
22
"""
23
24
def codes_get_array(msgid, key, ktype=None):
25
"""
26
Get key as array with automatic type detection.
27
28
Parameters:
29
- msgid (int): Message handle ID
30
- key (str): Key name
31
- ktype (int, optional): Force specific type conversion
32
33
Returns:
34
list: Array of values
35
"""
36
```
37
38
### Type-Specific Get Operations
39
40
Functions for retrieving values with explicit type conversion.
41
42
```python { .api }
43
def codes_get_long(msgid, key):
44
"""
45
Get key as long integer.
46
47
Parameters:
48
- msgid (int): Message handle ID
49
- key (str): Key name
50
51
Returns:
52
int: Key value as integer
53
"""
54
55
def codes_get_double(msgid, key):
56
"""
57
Get key as double precision float.
58
59
Parameters:
60
- msgid (int): Message handle ID
61
- key (str): Key name
62
63
Returns:
64
float: Key value as float
65
"""
66
67
def codes_get_string(msgid, key):
68
"""
69
Get key as string.
70
71
Parameters:
72
- msgid (int): Message handle ID
73
- key (str): Key name
74
75
Returns:
76
str: Key value as string
77
"""
78
79
def codes_get_long_array(msgid, key):
80
"""
81
Get key as long integer array.
82
83
Parameters:
84
- msgid (int): Message handle ID
85
- key (str): Key name
86
87
Returns:
88
list[int]: Array of integers
89
"""
90
91
def codes_get_double_array(msgid, key):
92
"""
93
Get key as double precision array.
94
95
Parameters:
96
- msgid (int): Message handle ID
97
- key (str): Key name
98
99
Returns:
100
list[float]: Array of floats
101
"""
102
103
def codes_get_float_array(msgid, key):
104
"""
105
Get key as float array.
106
107
Parameters:
108
- msgid (int): Message handle ID
109
- key (str): Key name
110
111
Returns:
112
list[float]: Array of floats
113
"""
114
115
def codes_get_string_array(msgid, key):
116
"""
117
Get key as string array.
118
119
Parameters:
120
- msgid (int): Message handle ID
121
- key (str): Key name
122
123
Returns:
124
list[str]: Array of strings
125
"""
126
```
127
128
### Element Access Operations
129
130
Functions for accessing specific elements within array keys.
131
132
```python { .api }
133
def codes_get_elements(msgid, key, indexes):
134
"""
135
Get specific array elements by index.
136
137
Parameters:
138
- msgid (int): Message handle ID
139
- key (str): Key name
140
- indexes (list[int]): List of element indexes
141
142
Returns:
143
list: Selected array elements
144
"""
145
146
def codes_get_double_element(msgid, key, index):
147
"""
148
Get single double element by index.
149
150
Parameters:
151
- msgid (int): Message handle ID
152
- key (str): Key name
153
- index (int): Element index
154
155
Returns:
156
float: Element value as float
157
"""
158
159
def codes_get_double_elements(msgid, key, indexes):
160
"""
161
Get multiple double elements by index.
162
163
Parameters:
164
- msgid (int): Message handle ID
165
- key (str): Key name
166
- indexes (list[int]): List of element indexes
167
168
Returns:
169
list[float]: Selected elements as floats
170
"""
171
```
172
173
### Generic Set Operations
174
175
Universal functions for setting values with automatic type detection.
176
177
```python { .api }
178
def codes_set(msgid, key, value):
179
"""
180
Set key value with automatic type detection.
181
182
Parameters:
183
- msgid (int): Message handle ID
184
- key (str): Key name
185
- value: Value to set (int, float, str, or list)
186
"""
187
188
def codes_set_array(msgid, key, value):
189
"""
190
Set key as array with automatic type detection.
191
192
Parameters:
193
- msgid (int): Message handle ID
194
- key (str): Key name
195
- value (list): Array values to set
196
"""
197
```
198
199
### Type-Specific Set Operations
200
201
Functions for setting values with explicit type conversion.
202
203
```python { .api }
204
def codes_set_long(msgid, key, value):
205
"""
206
Set key as long integer.
207
208
Parameters:
209
- msgid (int): Message handle ID
210
- key (str): Key name
211
- value (int): Integer value to set
212
"""
213
214
def codes_set_double(msgid, key, value):
215
"""
216
Set key as double precision float.
217
218
Parameters:
219
- msgid (int): Message handle ID
220
- key (str): Key name
221
- value (float): Float value to set
222
"""
223
224
def codes_set_string(msgid, key, value):
225
"""
226
Set key as string.
227
228
Parameters:
229
- msgid (int): Message handle ID
230
- key (str): Key name
231
- value (str): String value to set
232
"""
233
234
def codes_set_long_array(msgid, key, inarray):
235
"""
236
Set key as long integer array.
237
238
Parameters:
239
- msgid (int): Message handle ID
240
- key (str): Key name
241
- inarray (list[int]): Array of integers to set
242
"""
243
244
def codes_set_double_array(msgid, key, inarray):
245
"""
246
Set key as double precision array.
247
248
Parameters:
249
- msgid (int): Message handle ID
250
- key (str): Key name
251
- inarray (list[float]): Array of floats to set
252
"""
253
254
def codes_set_string_array(msgid, key, stringarray):
255
"""
256
Set key as string array.
257
258
Parameters:
259
- msgid (int): Message handle ID
260
- key (str): Key name
261
- stringarray (list[str]): Array of strings to set
262
"""
263
```
264
265
### Key Iteration
266
267
Functions for iterating through message keys.
268
269
```python { .api }
270
def codes_keys_iterator_new(msgid, namespace=None):
271
"""
272
Create keys iterator.
273
274
Parameters:
275
- msgid (int): Message handle ID
276
- namespace (str, optional): Key namespace filter
277
278
Returns:
279
int: Iterator handle ID
280
"""
281
282
def codes_keys_iterator_next(iterid):
283
"""
284
Move to next key.
285
286
Parameters:
287
- iterid (int): Iterator handle ID
288
289
Returns:
290
bool: True if next key exists, False if at end
291
"""
292
293
def codes_keys_iterator_get_name(iterid):
294
"""
295
Get current key name.
296
297
Parameters:
298
- iterid (int): Iterator handle ID
299
300
Returns:
301
str: Current key name
302
"""
303
304
def codes_keys_iterator_rewind(iterid):
305
"""Reset iterator to beginning."""
306
307
def codes_keys_iterator_delete(iterid):
308
"""Delete iterator and free memory."""
309
```
310
311
### Key Information and Validation
312
313
Functions for checking key properties and availability.
314
315
```python { .api }
316
def codes_is_defined(msgid, key):
317
"""
318
Check if key is defined in message.
319
320
Parameters:
321
- msgid (int): Message handle ID
322
- key (str): Key name
323
324
Returns:
325
bool: True if key exists, False otherwise
326
"""
327
328
def codes_is_missing(msgid, key):
329
"""
330
Check if key value is missing.
331
332
Parameters:
333
- msgid (int): Message handle ID
334
- key (str): Key name
335
336
Returns:
337
bool: True if value is missing, False otherwise
338
"""
339
340
def codes_get_size(msgid, key):
341
"""
342
Get size of key (array length or string length).
343
344
Parameters:
345
- msgid (int): Message handle ID
346
- key (str): Key name
347
348
Returns:
349
int: Size of key value
350
"""
351
352
def codes_get_length(msgid, key):
353
"""
354
Get length of key value.
355
356
Parameters:
357
- msgid (int): Message handle ID
358
- key (str): Key name
359
360
Returns:
361
int: Length of key value
362
"""
363
```
364
365
## Usage Examples
366
367
### Reading Common Meteorological Parameters
368
369
```python
370
import eccodes
371
372
with open('forecast.grib', 'rb') as f:
373
msg = eccodes.codes_grib_new_from_file(f)
374
375
# Read basic metadata
376
param_id = eccodes.codes_get(msg, 'paramId')
377
param_name = eccodes.codes_get(msg, 'name')
378
level = eccodes.codes_get(msg, 'level')
379
level_type = eccodes.codes_get(msg, 'levelType')
380
381
# Read time information
382
date = eccodes.codes_get(msg, 'dataDate')
383
time = eccodes.codes_get(msg, 'dataTime')
384
step = eccodes.codes_get(msg, 'step')
385
386
# Read grid information
387
grid_type = eccodes.codes_get(msg, 'gridType')
388
ni = eccodes.codes_get(msg, 'Ni') # longitude points
389
nj = eccodes.codes_get(msg, 'Nj') # latitude points
390
391
print(f"Parameter: {param_name} (ID: {param_id})")
392
print(f"Level: {level} {level_type}")
393
print(f"Date/Time: {date} {time:04d}Z + {step}h")
394
print(f"Grid: {grid_type} {ni}x{nj}")
395
396
eccodes.codes_release(msg)
397
```
398
399
### Modifying Message Parameters
400
401
```python
402
import eccodes
403
404
# Create new message from sample
405
msg = eccodes.codes_grib_new_from_samples('regular_ll_sfc_grib2')
406
407
# Set meteorological parameter
408
eccodes.codes_set(msg, 'paramId', 130) # Temperature
409
eccodes.codes_set(msg, 'name', 'Temperature')
410
411
# Set level information
412
eccodes.codes_set(msg, 'level', 850)
413
eccodes.codes_set(msg, 'levelType', 'isobaricInhPa')
414
415
# Set time information
416
eccodes.codes_set(msg, 'dataDate', 20231215)
417
eccodes.codes_set(msg, 'dataTime', 1200)
418
eccodes.codes_set(msg, 'step', 24)
419
420
# Set grid configuration
421
eccodes.codes_set(msg, 'Ni', 360) # 1 degree resolution
422
eccodes.codes_set(msg, 'Nj', 181) # 1 degree resolution
423
eccodes.codes_set(msg, 'iDirectionIncrement', 1000000) # in micro-degrees
424
eccodes.codes_set(msg, 'jDirectionIncrement', 1000000)
425
426
# Write modified message
427
with open('modified.grib', 'wb') as f:
428
eccodes.codes_write(msg, f)
429
430
eccodes.codes_release(msg)
431
```
432
433
### Working with Array Keys
434
435
```python
436
import eccodes
437
import numpy as np
438
439
with open('analysis.grib', 'rb') as f:
440
msg = eccodes.codes_grib_new_from_file(f)
441
442
# Check if key is an array
443
if eccodes.codes_get_size(msg, 'values') > 1:
444
# Get all data values
445
values = eccodes.codes_get_double_array(msg, 'values')
446
print(f"Data shape: {len(values)} points")
447
448
# Get grid coordinates if available
449
if eccodes.codes_is_defined(msg, 'latitudes'):
450
lats = eccodes.codes_get_double_array(msg, 'latitudes')
451
lons = eccodes.codes_get_double_array(msg, 'longitudes')
452
print(f"Coordinate arrays: {len(lats)} points")
453
454
# Get specific data points by index
455
sample_indices = [0, 100, 200]
456
sample_values = eccodes.codes_get_elements(msg, 'values', sample_indices)
457
print(f"Sample values: {sample_values}")
458
459
eccodes.codes_release(msg)
460
```
461
462
### Handling Missing Values
463
464
```python
465
import eccodes
466
467
with open('observations.bufr', 'rb') as f:
468
msg = eccodes.codes_bufr_new_from_file(f)
469
470
# Check key availability
471
temp_key = 'airTemperature'
472
if eccodes.codes_is_defined(msg, temp_key):
473
if not eccodes.codes_is_missing(msg, temp_key):
474
temperature = eccodes.codes_get(msg, temp_key)
475
print(f"Temperature: {temperature}°C")
476
else:
477
print("Temperature value is missing")
478
else:
479
print("Temperature key not available in this message")
480
481
eccodes.codes_release(msg)
482
```