Data Feed API - Extra
The extra items are numerically indexed and provide extra text to go along with numeric values such as weights or distances or even currencies. The attributes that use these extra indexes are all numeric and take two fields. You can send the data in a single field as long as you use the same short or long text that we keep in our database.
Although the data feed API can deliver information as JSON or XML, we are using XML here because it is easier to read.
<attribute> <extra_group>Distance</extra_group> <field_name>depth</field_name> <extra> <id>501</id> <extra_short>in</extra_short> <extra_long>inches</extra_long> <seq>10</seq> </extra> <extra> <id>503</id> <extra_short>ft</extra_short> <extra_long>feet</extra_long> <seq>20</seq> </extra> <extra> <id>505</id> <extra_short>yrd</extra_short> <extra_long>yards</extra_long> <seq>30</seq> </extra> </attribute>
Looking at this example, you can see that the EXTRA portion is an array of values each with their own properties. Here is what each section means:
- extra_group - The text name representing the type of information the extra value represents. The extra elements are associated with this group.
- field_name - The field that this extra information is attached to. Multiple fields can be attached to the same extra_group.
- id - This is the unique id that identifies the specific extra element. It is unique across all extra groups.
- extra_short - The short text used to enhance the main data item.
- extra_long - The long text used to enhance the main data item.
- seq - The sequence that we use to display this element in a list. When two sequence numbers are the same we sort by the extra_long value.
This extra information is normally used in a drop down box next to the numeric data field that we want to enhance. Some examples might be:
- 12 pounds
- 15.25 US Dollars
- 354 grams
- 12.4 ounces
- 12 lbs
- 15.25 USD
- 354 g
- 12.4 oz
You see we can display the long or short version of the extra code by using the ID index.
Fields that make use of this extra information require it when pushing data back to us in the feed. You can either send the data in two fields (value and extra_id) or in a single field (value) as long as the text following the numeric portion matches the long or short version of the extra data we store for the field.
For example, if you wanted to update a field that represented distance with the value "100 yards", you could either send that data just like that in the value field value=100+yards or in two seperate fields value=100&extra_id=505 and you would get the same results. If you send an invalid extra_id or text after the number that doesn't match our accepted list, your update would be rejected.