Address

Description

A a physical location to which one can travel or send mail.

Rules for proper formatting of addresses are set through the DMO here.

Label

:Address

Properties

The address properties are based on the schema.org entity GeoCoordinates which in turn incorporates PostalAddress.

Property	Type	Description / example
id	String	Unique identifier for this address, a uuid
type	String	The address type: see table below
primary	boolean
country	String	The three-letter ISO 3166-1 alpha-3 country code
locality	string	The locality, usually the city, in which the street address is, and which is in the region. For example, Nashville.
region	string	(optional) The region in which the locality is, and which is in the country. For example, California or Ontario or another appropriate first-level Administrative division.
regionAbbreviation	string	(optional) CA, ON, etc
extendedAddress	string	An address extension such as an apartment number, C/O or alternative name.
postOfficeBoxNumber	string	(optional) The post office box number for PO box addresses.
postalCode	string
streetAddress	string	9336 Civic Center Drive
geoPoint	point	The latitude and longitude of the address
createdBy	string	the person or process that created the node
createdDate	dateTime
modifiedBy	string	the person or process who last modified the node
modifiedDate	dateTime

INFO

Neo4j offers some level of geocoding support natively within the product, defaulting to OpenStreetMap (OSM); please refer to the spatial functions in the Neo4j documentation. The code example below shows how the geocoding can be done in-line with the address creation, however in a real application we'd do heavier validation before geocoding and we would of course check that the geocoding was successful before continuing.

The following address types will be valid for the type property on each :Address node, e.g., { type: "Home"}.

Type	Notes
Home	The home address of a party
Mailing	The address where a party or venue receive mail
Main	The primary contact address for a party / the physical location of a venue
Payment	Where checks get sent -- if we send checks
CorpHQ	Corporate Headquarters
Shipping	Address where physical items are sent
Billing	The address where bills/invoices are sent
RegionalOffice	Address associated with a regional office

Entities such as parties and venues can have multiple addresses of various types, any number of which can be active at one time and of course no limit to the number of inactive addresses. When used with a :Venue node, there can be only one active relationship to an address node of type "Main", This represents a venue's physical address.

Key

id

Relationships

The HAS_ADDRESS relationship connects parties to addresses, and uses the standard relationship properties.

INFO

Address verification: No address should be allowed into UTA systems that does not run through the address verification, normalization, and geocoding gate. So many upstream services based on location will depend on the accuracy of this information. We must ensure we use an address verification service (API) which:

1. returns a normalized address broken down into component parts,
2. returns the full geocoded latitude and longitude, and preferably elevation in meters, for that address, and
3. is able to verify addresses globally, including key countries in Asia. Many commercial address verification services are US-centric and should be avoided.

Examples

Add a mailing address to a party

MATCH   (party:Party { id: $id })
WITH    party,
        [
          $streetAddress,
          $locality,
          $regionAbbreviation,
          $postalCode,
          $country
        ] AS address
WITH    party, apoc.text.join(address, ' ') AS locname
CALL    apoc.spatial.geocodeOnce(locname) YIELD location
WITH    party, location, locname
MERGE   (party)-[rel:HAS_ADDRESS {
          id: randomUUID(),
          subType: "",
          active: true ,
          private: false ,
          fromDate: date(),
          thruDate: "",
          termReason: ""
        }]->(addr:Address {
          id: randomUUID(),
          type: "Mailing",
          country: $country,
          locality: $locality,
          region: $region,
          regionAbbreviation: $regionAbbreviation,
          postalCode: $postalCode,
          streetAddress: $streetAddress,
          postOfficeBoxNumber: "",
          geoPoint: point(longitude=location.longitude, latitude=location.latitude),
          elevation: "",
          createdBy: "Glenn Scott",
          createdDate: date(),
          modifiedBy: "Glenn Scott",
          modifiedDate: date()
        })
RETURN  party.id,
        party.name,
        addr{ .* }