Microformats Wiki - User contributions [en]

adr

2009-02-01T21:55:25Z

Txgaritano:

<entry-title>adr</entry-title>
{{DraftSpecification}}

'''adr''' (pronounced "adder"; FAQ: [[hcard-faq#Should_I_use_ADDRESS_for_hCards|"why 'adr'?"]]) is a simple format for marking up address information, suitable for embedding in HTML, XHTML, Atom, RSS, and arbitrary XML. '''adr''' is a 1:1 representation of the ''adr'' property in the vCard standard ([http://www.ietf.org/rfc/rfc2426.txt RFC2426]) in HTML, one of several open [[microformats|microformat]] standards. It is also a property of [[hCard]].

== Draft Specification ==
<div class="vcard">
; <span class="role">Editor</span>/<span class="role">Author</span>
: <span class="fn">[[User:Tantek|Tantek Çelik]]</span> (<span class="url">http://tantek.com/</span>, and before at [http://technorati.com Technorati, Inc.])
</div>

=== Copyright ===
Per the public domain release on [[User:Tantek|my user page]], this specification is released into the public domain.

{{MicroFormatPublicDomainContributionStatement}}

=== Patents ===
{{MicroFormatPatentStatement}}

=== Inspiration and Acknowledgments ===
Thanks to everyone who participated in the [[geo-bof-2005-06-30|Geo Microformat BOF at O'Reilly's Where 2.0 conference]], and in particular to [http://radar.oreilly.com/nat/ Nat Torkington] and Vee McMillen of [http://oreilly.com O'Reilly] for [http://conferences.oreillynet.com/cs/where2005/view/e_sess/7476 arranging and hosting the BOF].

== Introduction and Background ==
The vCard standard ([http://www.ietf.org/rfc/rfc2426.txt RFC2426]), has been broadly and interoperably implemented (e.g. Apple's Address Book application). The [[hcard|hCard]] microformat has similarly received significant adoption, from numerous sites publishing the format, to hCard to vCard proxies, to clientside javascript parsers.

At the [http://conferences.oreillynet.com/where/ Where 2.0 conference] in June 2005, there was widespread recognition that the community needed a way to simply and easily publish visible, extractable, address information on the Web, given how often bloggers, and numerous other sites publish address information. The [[geo-bof-2005-06-30|geo microformat BOF]] discussed this very topic, and concluded with a consensus decision to just try using ''adr'' from vCard/hCard.

This specification introduces the '''adr''' microformat, which is a 1:1 representation of the aforementioned ''adr'' property from the vCard standard, by simply reusing the ''adr'' property and sub-properties as-is from the [[hcard|hCard]] microformat.

Publishers can both embed '''adr''' addresses directly in their web pages and feeds, as well as markup existing addresses in the context of the rest of the information in their web pages and feeds.

If the publisher knows and is publishing the ''name'' of the location in addition to its address, then the publisher MUST use [[hcard|hCard]] instead of just '''adr''' to publish the name and address of the location.

== Semantic XHTML Design Principles ==
{{semantic-xhtml-design-principles}}

== Format ==
=== Singular Properties ===
See [[hcard#Singular_vs._Plural_Properties|hCard: Singular vs. Plural Properties]] for the list of which "adr" properties (sub-properties in hCard) are singular. Note analysis in progress: [[adr-singular-properties]].

=== Human vs. Machine readable ===
If an <code><abbr></code> element is used for a property, then the <code>title</code> attribute of the <code><abbr></code> element is the value of the property, instead of the contents of the element, which instead provide a human presentable version of the value.

Similarly, if an <code><img></code> element is used for one or more properties, it must be treated as follows:
# For the <code>PHOTO</code> property and any other property that takes a <abbr title="Uniform Resource Locator">URL</abbr> as its value, the <code>src</code> attribute provides the property value.
# For other properties, the <code><img></code> element's <code>alt</code> attribute is the value of the property.

=== Value excerpting ===
Sometimes only part of an element which is the equivalent for a property should be used for the value of the property. For this purpose, the special class name <code>value</code> is used to excerpt out the subset of the element that is the value of the property. See [[hcard|hCard]] for details on this.

=== Root Class Name ===

The root class name for an '''adr''' address is <code>adr</code>.

=== Property List ===

This is the list of properties in '''adr''', taken from [[hcard|hCard]]:

* <code>post-office-box</code>
* <code>extended-address</code>
* <code>street-address</code>
* <code>locality</code>
* <code>region</code>
* <code>postal-code</code>
* <code>country-name</code>

The <code>type</code> sub-property is omitted because without the context of a type of address for ''whom'', it doesn't make much sense.

=== XMDP Profile ===

See [[hcard-profile]] for the [http://gmpg.org/xmdp XMDP] profile of hCard which contains the above complete list of properties, with references to their RFC 2426 definitions.

=== Parsing Details ===
See [[hcard-parsing|hCard parsing]], with the only difference being that "adr" is the root class name, rather than "vcard".

== Examples ==
This section is informative.

=== Sample adr ===

Here is a sample <code>adr</code>:

<pre><nowiki>
<div class="adr">
<div class="street-address">665 3rd St.</div>
<div class="extended-address">Suite 207</div>
<span class="locality">San Francisco</span>,
<span class="region">CA</span>
<span class="postal-code">94107</span>
<div class="country-name">U.S.A.</div>
</div>
</nowiki></pre>

which might be displayed as:

<div class="adr">
<div class="street-address">'''665 3rd St.'''</div>
<div class="extended-address">'''Suite 207'''</div>
<span class="locality">'''San Francisco'''</span>,
<span class="region">'''CA'''</span>
<span class="postal-code">'''94107'''</span>
<div class="country-name">'''U.S.A.'''</div>
</div>

Note that this is a '''live''' <code>adr</code> microformat, which will be found on this page by parsers.

=== More Examples ===

See [http://microformats.org/wiki/hcard-examples#3.2.1_ADR_Type_Definition hCard example ADR] for more examples.

See [http://microformats.org/wiki/adr-examples adr examples] for additional uses of ADR.

== Examples in the wild ==
This section is '''informative'''.

The following sites have published adrs, outside their normal context of hCards, and thus are a great place to start for anyone looking for examples "in the wild" to try parsing, indexing, organizing etc., in addition to [[hcard|hCard]] examples in the wild. If you find adrs outside of hCards anywhere else, feel free to add them to the top of this list. Once the list grows too big, we'll make a separate wiki page.

* [http://www.growsonyou.com/visit Grows on You] uses the microformat to mark up the addresses of open gardens.
* [http://www.stems-florist.co.uk/ Stems Florist] uses the microformat on the front page to markup up the two store addresses
* [http://themechanism.com/locations/ theMechanism] uses the adr microformat to mark up the locations of
their offices.
* [http://www.mister-map.com/ Mister-Map.com] uses the adr microformat to mark up the streets, zip-codes, regions and country names.

(See also [[hcard-examples-in-wild]])

== Implementations ==
This section is '''informative'''.

The following implementations have been developed which either generate or parse adrs outside the context of hCards. If you have an adr implementation, feel free to add it to the top of this list. Once the list grows too big, we'll make a separate wiki page.

* [http://code.highearthorbit.com/greaseroute/index.php GreaseRoute] is a GreaseMonkey user script (also available as a simple Firefox Extension) which will add icons for displaying the location, or route to, an [[adr]] using a MapQuest map. The route is displayed from the starting location based on the viewer's IP-Address as determined by the [http://hostip.info HostIP] geolocation service.

* [http://code.highearthorbit.com/greaseroute/index.php GreaseRouteEmbed] is another GreaseMonkey user script that will actually embed a route image in the webpage when the user clicks the "route" link.

* [http://georss.org/geopress GeoPress] is a [http://wordpress.org WordPress] plugin that supports embedding adrs, geo, maps (dynamically switchable between Google-Yahoo-Microsoft Maps), and [http://georss.org GeoRSS] feeds.

* [http://placenamehere.com/TXP/pnh_mf/ pnh_mf] is a plugin for [http://textpattern.com/ Textpattern] that supports embedding adrs and other microformats in templates and blog posts. Written by [http://placenamehere.com/ Chris Casciano].

* The [http://tantek.com/microformats/hcard-creator.html hCard creator], though it creates complete hCards, can also be used simply to create adrs by filling out the address portion and simply copy and pasting the <div class="adr"> element and its contents.

== References ==
=== Normative References ===
* [[hcard|hCard]]

=== Informative References ===
* [http://www.ietf.org/rfc/rfc2426.txt vCard RFC2426] ([http://www.w3.org/2002/12/cal/rfc2426 HTML reformatted version of RFC2426])
* [http://www.w3.org/TR/2002/REC-xhtml1-20020801/ XHTML 1.0 SE]

=== Similar Work ===
* [[geo]]
* [[hcalendar|hCalendar]]
* [[XOXO]]

== Work in progress ==
This specification is a work in progress. As additional aspects are discussed, understood, and written, they will be added.

== Discussions ==

* See [http://www.technorati.com/cosmos/referer.html blogs discussing this page].

=== Q&A ===
* If you have any questions about hCard, check the [[hcard-faq|hCard FAQ]] first, and if you don't find answers, add your questions! (Odds are that any '''adr''' question will apply to [[hCard]] as well).
* See also [http://microformats.org/discuss/ for other methods of feedback].

=== Issues ===
* Please add any issues with the specification to the separate [[hcard-issues|hCard issues]] document. Ditto.

== Related Pages ==
{{adr}}

[[Category:Draft_Specifications]]
[[Category:hCard]]
[[Category:adr]]

location-formats

2009-02-01T21:50:25Z

Txgaritano: /* Mapping Sites */

<h1>location formats</h1>
{{TOC-right}}

This is a list of previous efforts at location / geographic ("Geo") data formats and protocols, as background research for developing [[location]] microformats. Continuation of work from [[location-examples]], and following onto [[location-brainstorming]].

== Authors ==
* [[User:Tantek|Tantek Çelik]]
* Bud Gibson
* Ryan King
* Eron Wright
* ...
* please add yourself if you help(ed) with this document.

== vCard & hCard ==
vCard (RFC2426) and [[hcard]] include 'adr', a way to markup addresses. They also have a field called 'geo' for lat/long.

== UPU S42 & OASIS xNAL ==
UPU S42 is a standard for representing postal addresses. UPU, the Universal Postal Union, is the consortium of all national posts. See [http://xml.coverpages.org/ni2003-06-17-a.html UPU S42 Announcement]. xNAL, the XML Name
and Address Language, is an earlier attempt to standardize on the components of addresses developed by OASIS,
a consortium of business-process weenies. The distinction between vCard/hCard and S42/xAL/xNAL comes down to
whether the address line elements themselves are decomposed. For example, in xNAL you can specify components like
street number, street prefix directional, street name, street type, street postfix directional, subaddress type (Suite), subaddress number.

It is not always possible to conclusively determine these components from an address line, even in the US where addresses are more canonical than others. "A 4TH ST W STE 10" is a legal address line in the US. The street number and name are required (in the US) so this could be canonically decomposed as streetnumber="A", streetname="4TH", streettype="ST", postdirectional="W", subtype="STE", subtypenumber="10".

UPU S42 and OASIS xNAL standards are likely overkill for tagging general web content. However, they are important standards that should be considered in web-services involving both geocoding and reverse-geocoding. Perhaps standards
related to decomposed addresses is something that should be placed on another page.

In addition, there should be pointers to national address standards.

USPS publishes a complete list of canonical abbreviations for both streettypes and subtypes. Their publications are self-inconsistent, but it is easy to infer the correct mappings. See [http://www.usps.com/ncsc/lookups/usps_abbreviations.htm USPS Acronyms & Abbreviations]

New Zealand apparently adopted a variant of xNAL [http://www.e-government.govt.nz/docs/xnal-guidelines-1-0/index.html NZ xNAL Guidelines Release 1.0].

== ICBM ==
One comma seperated pair of lat/long <code><meta name="ICBM" content="XXX.XXXXX, XXX.XXXXX"></code>
[http://www.catb.org/~esr/jargon/html/I/ICBM-address.html]

== GeoUrl ==
* [http://geourl.org/ GeoURL]
** This seems to have a decent amount of geeky adoption, though there are lots of typical invisible metadata problems, coordinates reversed, postive instead of negative etc.
* [http://www.multimap.com/ Multimap.com] provides similar functionality to GeoUrl, searching for websites and weblogs which are geotagged or ICBM tagged, and adding them to local information databases.

== Flickr Geotags ==
* [http://steeev.f2o.org/mt/2005/05/geotagging_flickr_with_google_maps_and_greasemonkey_part_2.html Flickr GeoTagging] A Greasemonkey script for adding lat and long tags to flick pictures. He uses Google Maps to get the lat and long. Users have to enter search terms (address, etc) and then select a point on the google map. Photos are tagged with "geo:lat=xx.xxxx", "geo:lon=xx.xxxx" and "geotagged" and aggregated at [http://geobloggers.com/]
* [http://flickr.com/groups/geotagging/ A Flickr Group related to the topic]
* [http://txfx.net/2005/05/17/flickr-google-maps-geobloggers/ A visual walkthrough of the technique.]
* As of today (2005-06-01), 14k photos have been geotagged on Flickr.
* [http://mappr.com mappr], [http://brainoff.com/worldkit/flick mapping flickr] also support these geotags.
* flickr also supports [http://www.flickr.com/services/api/flickr.photos.getExif.html EXIF headers], which can be used for storing location.
* [http://beta.plazes.com plazes] also allows flickr photos to be tagged with geotags

This is somewhat of a problem though, as mechanically generated "tags" are not really tags. Including/setting Flickr "Geotags" could be considered pollution of truly user entered text, since the text of geotags is merely an encoding for a point on a map.

== Geotagging ==
* Geotagging has been employed in other hosted services: [http://brainoff.com/worldkit/delicious/ delicious], [http://worldkit.typepad.com/ Typepad], [http://blog.360.yahoo.com/blog-yRZQpvY8cq2kWXBO5ZrxEmrwsg--?p=9 Yahoo 360], [http://www.zoto.com/users/geotags/ Zoto]

But what do these references to "geotagging" mean?

== RSS ==
Several people have tried putting geographic information into RSS.
* [http://postneo.com/icbm/ This site] uses icbm coordinates and has plugins for several blogging packages.
* [http://www.blogmapper.com/ BlogMapper] - appears to be adding a namespace to RSS.
* [http://www.feedmap.net/BlogMap/ BlogMap] - picks up RSS extension and meta tag values
* [http://brainoff.com/worldkit/doc/rss.php worldKit RSS docs] - worldKit advocates and understands various flavors of geocoded RSS; particularly the "geo" namespace.
* [http://earthquake.usgs.gov/recenteqsww/rss.html USGS earthquake feed] - most widely used geocoded RSS feed
* [http://brainoff.com/worldkit/doc/polygon.php Polygons and lines in polygons] - A simple format for expressing polygons and lines is defined for worldKit
* [http://developer.yahoo.net/maps/ Yahoo Maps API] - uses "geo" ( http://www.w3.org/2003/01/geo/wgs84_pos# ) and "ymaps" ( http://api.maps.yahoo.com/Maps/V1/AnnotatedMaps.xsd ) namespaces to spatially-reference RSS as part of its API, specifically geo:lat, geo:long, ymaps:Address, ymaps:CityState, ymaps:Zip
* [http://georss.org GeoRSS]

== RDF ==
* [http://www.geosemantics.org/ Geosemantics Interest Group]
* [http://esw.w3.org/topic/GeoOnion GeoOnion] - a SW vocuabulary for relating items by distance from each other.
* [http://www.mapbureau.com/rdfmap1.0/index.html RDFMap]
* [http://esw.w3.org/topic/GeoRDF GeoRDF] similar effort to collect prior art, for an effort in interoperability between OGC standards and various lightweight geo formats.

== GML ==
[http://www.opengeospatial.org/docs/02-023r4.pdf Geographic Markup Language] provides the most complete XML descriptiono of geographic information available. Fortunately, it is also in wide-spread use, so a commonly-used subset of the 600-page specification has emerged. GML is used in the OGC WFS payload described below.

<blockquote style="background: white; border: 1px solid black; padding: 1em;">
== Open Geospatical Consortium - OGC ==
Since 1994, [http://www.opengeospatial.org/ Open Geospatial Consortium] has been developing open specifications to enable the exchange of geographic information between applications. While some GIS vendors opposed OGC initially, essentially all commercial GIS software companies have broken down their proprietary "stovepipes" by embracing OGC specifications. The recent groundswell of ajax mapping applications can benefit tremendously from using OGC specs.

=== WMS ===
The [http://portal.opengeospatial.org/files/?artifact_id=5316 OGC Web Map Service (WMS) specification] makes it easy to request map images from a map rendering engine, such as the [http://mapserver.gis.umn.edu/ UMN Map Server]. It is straightforward to build dynamic tiling ("slippy map") ajax applications that pull in OGC map tiles. At Where 2.0, [http://www.metacarta.com MetaCarta] demonstrated such an OGC-capable ajax GIS client. The portal map providers (yahoo/gmaps/msn/map quest) do not yet offer WMS interfaces, so someone should wrap their proprietary interfaces in a WMS wrapper to encourage them :-)

=== WCS ===

Web Coverage Service extends WMS to enable attribute information about large area overview maps.

=== WFS ===
The [https://portal.opengeospatial.org/files/?artifact_id=8339 OGC Web Feature Service (WFS) specification] is the best way to express geographic information about Web content. It is more complex than the <i>ad hoc</i> geoURL syntax, and for good reason: it can be loaded directly into any OGC-capable GIS even if the coordinate information is in a different projection/datum or is more complex than just a point.

WFS provides a robust means of querying for geographic entities, such as points, polygons, and more complex feature types. One can define new feature types simply by describing them. One can even specify the visual appearance of the geographic features using the [https://portal.opengeospatial.org/files/?artifact_id=1188 OGC Styled Layer Description (SLD) specification].

WFS is to vector map data, as WMS is to raster map data.

Geographic search results, such as the yellow page information from the portals, could be presented in WFS. John Battelle commented that RSS forces publishers to attach their business model to their content, instead of to the web site holding the content, so that they can make money no matter where their content flows. The search portals will probably be forced to do the same, e.g. putting click-through ads in the RSS search results or WFS yellow page results, so that even when you display them in your customized ajax mapping application, the portal publishing the search results can still make money.

</blockquote>

== Google ==
=== Google Earth XML ===
20050629 at Where 2.0 conference:
"Google Earth has an XML schema for describing a place on the earth. Will be releasing today or tomorrow."
- John Hanke of Google/Keyhole.
Official KML [http://www.keyhole.com/kml/kml_doc.html Docs] and [http://www.keyhole.com/kml/kml_tut.html Tutorial]

[http://bbs.keyhole.com/ubb/showthreaded.php/Cat/0/Number/16076/an/khGlobe/page/0#16076 Reverse-Engineered KML Schema] (deprecated now that KML 2.0 is officially released)

Note that KML supports the ''altitude'' component of a coordinate to support 3D terrain.

== NMEA ==

[http://www.gpsinformation.org/dale/nmea.htmhttp://www.gpsinformation.org/dale/nmea.htm Standard and Proprietary NMEA Sentances]

== Wikipedia ==

[http://en.wikipedia.org/wiki/Wikipedia:WikiProject_Geographical_coordinates Geo:Coordinates in Wikipedia Project]

== ISO6709 ==
[http://en.wikipedia.org/wiki/ISO_6709 : ISO6709 Alpha-numerical representation of Latitude,Longitude,(Altitude)]

== Other Formats ==

* GPX = GPS XML format
* [http://en.wikipedia.org/wiki/Wikipedia:WikiProject_Geographical_coordinates Wikipedia markup styles]
* [http://openguides.org/ OpenGuides] and [http://b.evnt.org evnt] are both looking into real-world/folksonomic location name mappings

== Location APIs ==

=== Google Maps API ===
* [http://www.google.com/apis/maps/ Google Maps API documentation]

=== Yahoo Maps API ===
* [http://developer.yahoo.net/maps/ Yahoo Maps API documentation]

== Location Data, Tools and Sites ==

=== Address2Coordinates ===
These systems are freely available sources of address to lat/long mappings (US only). The first few are based on US Census data, so they might be up to date.
* [http://www.census.gov/geo/www/tiger/ TIGER]
* [http://www.itl.nist.gov/fipspubs/55new/nav-top-fr.htm FIPS]
* [http://geocoder.us/ geocoder]
* You can get coordinates from UK post-codes from [http://www.streetmap.co.uk streetmap]
* Worldwide city level location data (over 4 million entries) is available from the [http://earth-info.nga.mil/gns/html/ GNS]. This is accessible as a REST service from the [http://brainoff.com/geocoder/ worldkit geocoder]
* [http://www.mysociety.org/?p=83 mysociety.org] is providing an interesting name-based location look-up services. The results are returned as a CSV file!   For instance, the query [http://gaze.mysociety.org/gaze-rest?f=find_places&country=US&state=CA&query=sunnyvale http://gaze.mysociety.org/gaze-rest?f=find_places&country=US&state=CA&query=sunnyvale] returns

<pre>
"Name","In","Near","Latitude","Longitude","State","Score"
"Sunnyvale","Santa Clara County","","37.36889","-122.03528","CA","100"
</pre>
but with a mime-type (text/csv) that browsers don't understand.

=== A2B ===
[http://www.a2b.cc/ A2B] is a location based search engine. Lat and long only. Seems to pick stuff up from geo meta tags. Pages can either be manually entered or [http://www.a2b.cc/help-searching-addurl-blogping.a2b pinged]. They support lat/long and ICBM meta tags.

=== Plazes ===
[http://plazes.com Plazes] is a system that does geo-info based on the network access point that the user's computer is connected to. They use tagging to identify locations.

=== Mapping Sites ===
* [http://www.multimap.com Multimap]
* [http://maps.google.com Google Maps]
* [http://www.mapquest.com MapQuest]
* [http://maps.yahoo.com Yahoo Maps]
* [http://www.mapblast.com MapBlast]
* [http://mapufacture.com mapufacture]
* [http://www.mister-map.com Mister-Map]

== see also ==
* [[location]]
* [[location-examples]]
* [[location-brainstorming]]