address_protocol.markdown

Very Simple Address Protocol

This is the standard way we encode addresses at Hudora. The Address Protocol can be implemented in XML, JSON, as object attributes in your programming language of choice or whatever. The field names are in german. Consider them a "terminus technicus". This helps to avoid name clashes with other formats.

The Address Protocol ist designed to be easy to encode in a wide range of formats.

Required Fields

• name1 - primary name identifying the recipient
• name2 - additional information identifying the recipient or additional adressing information. May be empty.
• strasse - addressing information, usually the street address. might be empty.
• land - country (ISO 3166, 2-letter country code)
• plz - zip code, might be empty (e.g. in Ireland. Note that even in the US the ZIP code seems sufficient for adressing, the name of the State is redundant).
• ort - city name

Optional fields

• name3 - additional information identifying the recipient or additional adressing information. May be dropped during processing. Put noting important in here!
• tel - phone number relevant to the address/delivery (formated like DIN 5008 or E.123)
• fax - fax number relevant to the address/delivery (formated like DIN 5008 or E.123)
• mobil - additional phone number relevant to the address/delivery (formated like DIN 5008 or E.123)
• mail - E-Mail address relevant to the address/delivery
• iln - GLN, the worldwide uniqe number of that company/address allocated by GS1 Note that there is an URN format to write ILNs, e.g. urn:epc:id:sgln:0614141.33254.0, see RfC 5134 for details. For now we don't use this format.

Additional Explanation

Field length is not defined. We have seen that field lengths longer than 32 characters have a high propability of beeing truncated. Based on E.164 Phone, Fax and Mobile Numbers should not be longer than 19 characters (15 digits and one '+' one '-' and two spaces). PLZ should never be longer than 10 characters.

All information should be related to the (delivery) address. If we for example talking about an order, the Phone Number should not be the person who ordered (e.g. the office) but the person who can give information about delivery (e.g. the warehouse). In practice this is often the same.

The E-Mail address might be used to send delivery status messages.

ISO 3166-1 alpha-2 country codes are the the codes you now from internet top level domain names. FR, BE, CH, AT, UK, US, DE, etc.

Examples

XML

This example encodes the address protocol as Plain Old XML (POX):

<address> 
  <name1>HUDORA GmbH</name1>
  <name2>Abt. Cybernetics</name2>
  <name3>Anlieferung: Tor 2</name3>
  <strasse>Jägerwald 13</strasse>
  <land>DE</land>
  <plz>42897</plz>
  <ort>Remscheid</ort>
  <tel>+49 2191 60912 0</tel>
  <fax>+49 2191 60912 50</fax>
  <mobil>+49 175 00000xx</mobil>
  <email>nobody@hudora.de</email>
  <iln>4005998000007</iln>
</address>

HTML

This example combines the adress protocol and hCard microformat into Plain Old Semantic HTML (POSH). This can be created from the XML-Example above by using an XSLT stylesheet:

<div id="hcard-example" class="vcard deHudoraAddress">
  <div>
    <span class="name1 org fn">HUDORA GmbH</span><br />
    <span class="name2 extended-address">Abt. Cybernetics</span><br/>
    <span class="name3 extended-address">Anlieferung: Tor 2</span>
  </div>
  <div class="adr">
    <div class="street-address strasse">Jägerwald 13</div>
    <div>
      <span class="country-name land">DE</span>
      <span class="postal-code plz">42897</span>
      <span class="locality ort">Remscheid</span>
    </div>
  </div>
  
  <br/>
  
  <div>
    <div>Tel.:  <span class="tel work">+49 2191 60912 0</span></div>
    <div>Fax:   <span class="tel fax" type="fax">+49 2191 60912 50</span></div>
    <div>Mobil: <span class="tel mobil" type="cell">+49 175 00000xx</span></div>
    <div>Mail:  <a class="email" href="mailto:nobody@hudora.de">nobody@hudora.de</a></div>
    <div>ILN:   <span class="iln">4005998000007</span></div>
  </div>
</div>

JSON

{"iln": "4005998000007",
 "name1": "HUDORA GmbH",
 "name2": "Abt. Cybernetics",
 "name3": "Anlieferung: Tor 2",
 "strasse": "J\\u00e4gerwald 13", 
 "ort": "Remscheid",
 "plz": "42897",
 "land": "DE",
 "tel": "+49 2191 60912 0",
 "fax": "+49 2191 60912 50",
 "mobil": "+49 175 00000xx",
 "email": "nobody@hudora.de"}

Python

address = {
  'name1':   'HUDORA GmbH',
  'name2':   'Abt. Cybernetics',
  'name3':   'Anlieferung: Tor 2',
  'strasse': 'Jägerwald 13',
  'land':    'DE',
  'plz':     '42897',
  'ort':     'Remscheid',
  'tel':     '+49 2191 60912 0',
  'fax':     '+49 2191 60912 50',
  'mobil':   '+49 175 00000xx',
  'email':   'nobody@hudora.de',
  'iln':     '4005998000007',
}

Alternatives

• vCard and hCard.
• EDIFACT NAD, LOC or ADR Segments.
• ammazon Fulfillment Web Service Address data type

See Also

VerySimpleOrderProtocol and LieferungProtocol.