h-adr: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
m (corrected intro)
m (s/<source>/<syntaxhighlight>/)
 
(34 intermediate revisions by 7 users not shown)
Line 1: Line 1:
<entry-title>h-adr</entry-title>
<dfn style="font-style:normal;font-weight:bold">h-adr</dfn> is a simple, open format for publishing structured locations such as addresses, physical and/or postal. h-adr is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML.
<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
----
<dfn style="font-style:normal;font-weight:bold">h-adr</dfn> is a simple, open format for publishing postal address information on the web. h-adr is one of several open [[microformats|microformat]] draft standards suitable for embedding data in HTML/HTML5.


h-adr is the [[microformats-2]] replacement for [[adr]]. It is most commonly used as part of an [[h-card]] or [[h-event]].
h-adr is the [[microformats-2]] update to [[adr]]. It is most commonly used as part of an [[h-card]] or [[h-event]].
 
For named addresses, e.g. people or venues, use [[h-card]].
 
;<span id="Status">Status</span>
:This is a '''Draft Specification'''
;Participate
:[[IRC]]: [irc://irc.libera.chat/microformats #microformats on Libera]
;Editor
:<span class="h-card vcard"><span class="p-name fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="p-role role">Editor</span>)</span>
;License
:{{cc0-owfa-license}}
__TOC__


== Example ==
== Example ==
Here is a simple minimal person example:
Here is a simple postal address example:


<source lang=html4strict>
<syntaxhighlight lang="html">
<p class="p-adr h-adr">
<p class="h-adr">
   <span class="p-street-address">17 Austerstræti</span>
   <span class="p-street-address">17 Austerstræti</span>
   <span class="p-locality">Reykjavík</span>
   <span class="p-locality">Reykjavík</span>
Line 16: Line 25:
   <span class="p-postal-code">107</span>
   <span class="p-postal-code">107</span>
</p>
</p>
</source>
</syntaxhighlight>
 
Parsed JSON:
 
<syntaxhighlight lang="json">
{
  "items": [
    {
      "type": [
        "h-adr"
      ],
      "properties": {
        "street-address": [
          "17 Austerstræti"
        ],
        "locality": [
          "Reykjavík"
        ],
        "country-name": [
          "Iceland"
        ],
        "postal-code": [
          "107"
        ],
        "name": [
          "17 Austerstræti Reykjavík Iceland 107"
        ]
      }
    }
  ]
}
</syntaxhighlight>
 
The implicit "name" property that is generated from parsing an h-adr is there for consuming applications to have a simple flattened string representation of an h-adr.
 
For an explicitly named address (such as a mailing address to a specific person), use [[h-card]].


=== Get started ===
=== Get started ===
The class '''<code>h-adr</code>''' is a ''root class name'' that indicates the presence of an h-adr.
The class '''<code>h-adr</code>''' is a ''root class name'' that indicates the presence of an h-adr.


'''p-street-address''', '''p-extended-address''' and all the other h-adr property classnames define an element as a ''property'' of the h-adr.
'''p-street-address''', '''p-locality''', '''p-country-name''', '''p-postal-code''' and all the other h-adr property class names listed below define properties of the h-adr.


See [[microformats-2-parsing]] to learn more about property classnames.
See [[microformats-2-parsing]] to learn more about property class names.


== Properties ==
== Properties ==
 
h-adr properties, inside an element with class '''h-adr''':
* '''<code>p-street-address</code>''' - house/apartment number, floor, street name
* '''<code>p-street-address</code>''' - house/apartment number, floor, street name
* '''<code>p-extended-address</code>''' - additional street details
* '''<code>p-extended-address</code>''' - additional street details
* '''<code>p-post-office-box</code>'''
* '''<code>p-post-office-box</code>''' - post office mailbox
* '''<code>p-locality</code>''' - city/town/village
* '''<code>p-locality</code>''' - city/town/village
* '''<code>p-region</code>''' - state/county/province
* '''<code>p-region</code>''' - state/county/province
* '''<code>p-postal-code</code>''' - postal code, e.g. ZIP in the US
* '''<code>p-postal-code</code>''' - postal code, e.g. ZIP in the US
* '''<code>p-country-name</code>''' - country name
* '''<code>p-country-name</code>''' - should be full name of country, country code ok
* '''<code>p-label</code>''' - new in vCard4 (RFC6350)
* '''<code>p-label</code>''' - a mailing label, plain text, perhaps with preformatting
* '''<code>p-geo</code>''' (or u-geo with a RFC 5870 geo: URL), optionally a nested [[h-geo]]
* '''<code>p-geo</code>''' (or u-geo with a RFC 5870 geo: URL), optionally embedded [[h-geo]]
* '''<code>p-latitude</code>''' - metric latitude
* '''<code>p-latitude</code>''' - decimal latitude
* '''<code>p-longitude</code>''' - metric longitude
* '''<code>p-longitude</code>''' - decimal longitude
* '''<code>p-altitude</code>''' - metric altitude
* '''<code>p-altitude</code>''' - decimal altitude - new in vCard4 (RFC6350)


All properties are optional.
* '''<code>p-name</code>''' - there is no "p-name" property in h-adr. If your address has an explicit name, it's likely a venue, and you should use [[h-card]] instead.
== Status ==
'''h-adr''' is a microformats.org draft specification. Public discussion on h-adr takes place on [[h-adr-feedback]] and the #microformats [[irc]] channel on irc.freenode.net.
h-adr is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-adrs up with classic [[adr]] classnames.
== Property Details ==
(stub, add any property explanations here)
== Examples in the Wild ==
* … add any h-adr examples you find in the wild
== Validating ==
{{h-spec-section-validating}}
== Backward Compatibility ==
=== Publisher Compatibility ===
For backward compatibility, you may wish to use classic [[adr]] classnames in addition to the more future-proof h-adr properties, for example:
For backward compatibility, you may wish to use classic [[adr]] classnames in addition to the more future-proof h-adr properties, for example:


<source lang=html4strict>
<syntaxhighlight lang="html">
<span class="p-street-address street-address">123 Main St.</span>
<p class="h-adr adr">
</source>
  <span class="p-street-address street-address">123 Main St.</span>,
  <span class="p-locality locality">Pleasantville</span>
  ...
</p>
</syntaxhighlight>


Microformats parsers should detect classic properties and parse them as microformats 2 properties. If an "h-adr" is found, don't look for an "adr" on the same element.
The class '''<code>adr</code>''' is a ''backward compatible root class name'' that indicates the presence of an [[adr]].
 
'''street-address''', '''locality''', and all the other backward compatibility adr property class names are listed below.
 
=== Parser Compatibility ===
Microformats parsers should detect classic properties only if a classic root class name is found and parse them as microformats2 properties.  
 
If an "h-adr" is found, don't look for an "adr" on the same element.


Compatibility root class name: adr
Compatibility root class name: adr
Line 60: Line 135:
* country-name
* country-name


== Status ==
== FAQ ==
 
=== What about country codes ===
'''h-adr''' is a microformats.org draft specification. Public discussion on h-adr takes place on [[h-adr-feedback]], the #microformats [[irc]] channel on irc.freenode.net, and [http://microformats.org/discuss/mail/microformats-new/ microformats-new mailing list].
Q: When marking up an address, can p-country-name be used to markup two letter country codes like "UK"? Or others like 3 letter Olympic country codes?
 
h-adr is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-adrs up with classic [[adr]] classnames.
 
== Property Details ==


(stub, add any property explanations here)
A: In short yes. You can do:
<syntaxhighlight lang="html">
<span class="p-country-name">UK</span>
</syntaxhighlight>
However it's better if you mark it up with the <code>abbr</code> element and provide the full name as well, e.g.
<syntaxhighlight lang="html">
<abbr class="p-country-name" title="United Kingdom">UK</abbr>
</syntaxhighlight>


== Examples in the Wild ==
Consuming applications may interpret any 2-3 character country-name per the table of 2-3 character [http://en.wikipedia.org/wiki/ISO_3166-1#Officially_assigned_code_elements country codes in ISO3166].
 
* … add any h-adr examples you find in the wild


== Background ==
== Background ==
h-adr is based on the existing [[adr]] specification, which was extracted from [[hCard]] in order to allow it to be used for applications other than contact information.
h-adr is based on the existing [[adr]] specification, which was extracted from [[hCard]] in order to allow it to be used for applications other than contact information.


== See Also ==
== See Also ==
* [[microformats2]]
* [[h-geo]] can be embedded in h-adr
* [[h-card]] and [[h-event]] often contain h-adr
* [[vcard]] (most recently vCard4 RFC6350) vocabulary is re-used by h-adr.
* [[address-formats]]


* [[microformats-2]]
[[Category:Draft Specifications]]
* [[h-geo]] can be nested in h-adr
* [[h-card]] and [[h-event]] often contain h-adr

Latest revision as of 21:13, 26 July 2023

h-adr is a simple, open format for publishing structured locations such as addresses, physical and/or postal. h-adr is one of several open microformat draft standards suitable for embedding data in HTML.

h-adr is the microformats-2 update to adr. It is most commonly used as part of an h-card or h-event.

For named addresses, e.g. people or venues, use h-card.

Status
This is a Draft Specification
Participate
IRC: #microformats on Libera
Editor
Tantek Çelik (Editor)
License
Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2024-03-28, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.

Example

Here is a simple postal address example:

<p class="h-adr">
  <span class="p-street-address">17 Austerstræti</span>
  <span class="p-locality">Reykjavík</span>
  <span class="p-country-name">Iceland</span>
  <span class="p-postal-code">107</span>
</p>

Parsed JSON:

{
  "items": [
    {
      "type": [
        "h-adr"
      ],
      "properties": {
        "street-address": [
          "17 Austerstræti"
        ],
        "locality": [
          "Reykjavík"
        ],
        "country-name": [
          "Iceland"
        ],
        "postal-code": [
          "107"
        ],
        "name": [
          "17 Austerstræti Reykjavík Iceland 107"
        ]
      }
    }
  ]
}

The implicit "name" property that is generated from parsing an h-adr is there for consuming applications to have a simple flattened string representation of an h-adr.

For an explicitly named address (such as a mailing address to a specific person), use h-card.

Get started

The class h-adr is a root class name that indicates the presence of an h-adr.

p-street-address, p-locality, p-country-name, p-postal-code and all the other h-adr property class names listed below define properties of the h-adr.

See microformats-2-parsing to learn more about property class names.

Properties

h-adr properties, inside an element with class h-adr:

  • p-street-address - house/apartment number, floor, street name
  • p-extended-address - additional street details
  • p-post-office-box - post office mailbox
  • p-locality - city/town/village
  • p-region - state/county/province
  • p-postal-code - postal code, e.g. ZIP in the US
  • p-country-name - should be full name of country, country code ok
  • p-label - a mailing label, plain text, perhaps with preformatting
  • p-geo (or u-geo with a RFC 5870 geo: URL), optionally embedded h-geo
  • p-latitude - decimal latitude
  • p-longitude - decimal longitude
  • p-altitude - decimal altitude - new in vCard4 (RFC6350)

All properties are optional.

  • p-name - there is no "p-name" property in h-adr. If your address has an explicit name, it's likely a venue, and you should use h-card instead.

Status

h-adr is a microformats.org draft specification. Public discussion on h-adr takes place on h-adr-feedback and the #microformats irc channel on irc.freenode.net.

h-adr is ready to use and implemented in the wild, but for backwards compatibility you should also mark h-adrs up with classic adr classnames.

Property Details

(stub, add any property explanations here)

Examples in the Wild

  • … add any h-adr examples you find in the wild

Validating

Main article: validators

Test and validate microformats2 markup in general with:

Backward Compatibility

Publisher Compatibility

For backward compatibility, you may wish to use classic adr classnames in addition to the more future-proof h-adr properties, for example:

<p class="h-adr adr">
  <span class="p-street-address street-address">123 Main St.</span>, 
  <span class="p-locality locality">Pleasantville</span>
  ...
</p>

The class adr is a backward compatible root class name that indicates the presence of an adr.

street-address, locality, and all the other backward compatibility adr property class names are listed below.

Parser Compatibility

Microformats parsers should detect classic properties only if a classic root class name is found and parse them as microformats2 properties.

If an "h-adr" is found, don't look for an "adr" on the same element.

Compatibility root class name: adr

Properties: (parsed as p- plain text unless otherwise specified)

  • post-office-box
  • extended-address
  • street-address
  • locality
  • region
  • postal-code
  • country-name

FAQ

What about country codes

Q: When marking up an address, can p-country-name be used to markup two letter country codes like "UK"? Or others like 3 letter Olympic country codes?

A: In short yes. You can do:

<span class="p-country-name">UK</span>

However it's better if you mark it up with the abbr element and provide the full name as well, e.g.

<abbr class="p-country-name" title="United Kingdom">UK</abbr>

Consuming applications may interpret any 2-3 character country-name per the table of 2-3 character country codes in ISO3166.

Background

h-adr is based on the existing adr specification, which was extracted from hCard in order to allow it to be used for applications other than contact information.

See Also