Places Requirements
by John Mileham and Oumi Mehrotra
I. Introduction
This document lays out the requirements for an ACS service for uniquely
identifying geographic locations.
II. Vision Statement
There are many situations where an address or location needs to mean more to
a web service than a few text fields and a ZIP code. Providing a standard
mechanism for storing this information in a readily accessible format allows
for applications such as geo-centric bboards, dealer locators, and regional
usage statistics to be developed quickly and easily. The
places service also meets the need to internationalize the representation of
geographic locations by supporting but not requiring arbitrary country-specific
levels of organization, such as ZIP codes and states in the US.
III. System/Application Overview
The places service provides a storage mechanism for physical
places, in addition to a standard data set of countries and US states. The
places system also provides an API for adding places and place types, assigning
places to ACS objects, and answering essential questions about place-object
associations (i.e. determining the location of any ACS object in the database
that has been assigned one).
IV. Use-cases and User-scenarios
A typical use for the places service would be the address book application,
which makes use of places to store physical addresses. In a geocentric bboard, forums could be created
and associated with any place, be it a country, state, or any implementation-specific place-type. ZIP code
searches could be performed easily as every place in the database may carry latitude/longitude values.
As an added benefit of latitude/longitude support of all places, radius searches could be performed with
less specific data (such as a state or country). There are internationalization benefits as well. This
system allows for radius searches to be carried out
in countries that may not have a postal code system (or in a country with an entirely seperate postal code
system), though the latitude/longitude data and new place types for the applicable places would, no doubt,
need to be added by the implementor of such a system through the API provided by the places service.
Competitive Analysis
In ACS 3.x, there was no ACS-global representation of a physical location or an address. The places
service allows many applications to access and edit this information in a standard way, sharing and reusing
geographic data. Modeling the concept that places exist within other places allows
us to verify integrity of address information before inserting it into the database (e.g. "New Jersey is not in
France. Please go back and correct this error."). This system adds concrete semantic value to data that
would traditionally be stored in an application specific table containing hard-references to ACS geo
tables. The creation of a storage system where ACS "understands" the data it is keeping track of will allow
us to apply the data in countless ways in the future.
V. Related Links
VI.A Requirements: Data Model
10.0 Place Identification
A place must have the following attributes:
10.01 place_id (primary key) that is guaranteed to be unique
to the local ACS site.
10.07 Place Type
10.10 Type-Specific attributes
Each place type may have additional attributes associated with it. For
example, the state place-type may define a usps_abbrev
attribute to store the two-letter US Postal Service state name abbreviation. Many
place types may carry a name attribute as well.
10.20 Latitude/Longitude
All places may carry values for latitude and longitude, though these values
are not required.
12.0 Aggregate Places
Places may be related to each other to represent containment. That
is, one place may be entirely contained by any other place. The
integrity of this relationship must be automatically maintained through
all data changes.
12.10 Transitivity
The Location Relationship represents a transitive relationship. That is,
if a place "Boston" belongs to place "MA", and place "MA" automatically
belongs to place "US", "Boston" must belong to place "US".
12.20 Unique direct parent
Each place may have at most one parent place. This
requirement prevents one geographically distinct place from belonging
to two places in different areas. For example, the 02139 ZIP code can
not belong to both Cambridge and Pasadena. Note that the 02139 zip code
automatically will belong to all parent places of Cambridge through the
transitivity requirement, but that this does not violate the general
idea of one geographic place existing in more than one place.
13.0 Integration with ACS Object Model
The Places package must integrate with the ACS Object Model.
13.10 Place-Object Association
Each ACS Object may be associated with 0 or more Places to represent
application-specific associations (such as addresses being associated
with an individual contact in address-book). We map multiple
places to individual ACS objects for two reasons. First, physical
locations often have multiple addresses. For example, ArsDigita, though
a single entity, and
possibly represented as a single object in ACS, may have several
addresses for different purposes (e.g. a P.O. box and a street address).
Second, ACS objects are not guaranteed to be geographically static
or distinct. For instance, an address-book contact is an ACS object,
though it may contain several different addresses (like a work address,
a home address, etc).
13.20 Transitivity with respect to place aggregation
An object that is associated with a place must also be indirectly
associated with all of that place's ancestors. This would allow us to
say that a geocentric bboard post about Boston would be indirectly
associated with Massachusetts and the United States.
15.0 Predefined Place Types
The system must define a few standard place types, including country,
state/province, and address. This does not mean that runtime place type definitions
will be restricted.
11.10 The "country" place type
Countries will have unique names.
11.20 The "state/province" place type
States will have names unique within their countries.
11.30 The "address" place type
The address place type will provide storage for information not modeled
in other place types, as it would be impossible (and not very desirable)
to model or maintain data integrity for address numbers as they relate to
street names the world over, for example.
VI.B Requirements: Data
20.0 A data set of all countries and US states
The service will contain all countries, US states and Canadian provinces to
allow for creation of basic UI elements such as state dropdown boxes for
dependant applications. In future, this may also include a large number of
cities and their lattitudes and longitudes to enable geographic searching
etc.
VI.B Requirements: API
30.0 Answer the question "What places is object X directly associated with?"
31.0 Answer the question "What places is object X indirectly associated with?"
35.0 Answer the question "What objects are associated with place X?"
40.0 Creation of place types
An API must exist to allow for creation of new place types (e.g. continents)
not specified by default in the distribution.
50.0 Creation of places
Application programmers must be able to add places to the places system as we
can not guarantee knowledge of all cities in the world, etc.
60.0 Assign a place to an object (via location relationship)
65.0 Consistency check
Places must provide the ability to check place containment up the hierarchy before
insert (e.g. rejecting creation of an address that attempts to place itself in New Jersey, France).
70.0 Provide ACS 3.x style API for place interaction
Though there are many benefits of the hierarchical representation of place information,
views and place-creation API should be provided to allow application programmers to
make use of the places service without worrying about its internal structure.
80.0 Efficiency
Since applications may ask the questions outlined in 30.0-35.0
frequently, and there may be heavy demand for place attributes (such as latitude/longitude
in the case of radius searches), the data model must support the efficient storage
and retrieval of place attributes and containment.
VII. Revision History
| Document Revision # |
Action Taken, Notes |
When? |
By Whom? |
| 0.1 |
Creation |
11/08/2000 |
John Mileham |
| 0.2 |
Clarified |
11/22/2000 |
John Mileham |
| 0.3 |
Rewritten |
11/27/2000 |
John Mileham (w/ significant input from Oumi Mehrotra) |
| 0.4 |
Revised |
11/29/2000 |
John Mileham and Oumi Mehrotra |
| 0.5 |
Revised |
12/05/2000 |
John Mileham w/input from Michael Bryzek |
jmileham@arsdigita.com
Last modified: $Date: 2001/04/20 20:51:14 $