This document identifies ways in which the CivicRec recreation management system can be integrated with the ArcGIS Geographical Information System. Typically, this integration is intended to allow City and County parks and recreation departments the opportunity to price programs or base access on a patron’s residency status.
There are no specific software requirements for integration between CivicRec and ArcGIS, however professional services fees apply to work performed by CivicRec to enable this integration. The customer is responsible for ensuring that the ArcGIS version being used supports the integration methods described below.
There are two integration methods discussed in this document:
- Manual address import
- REST (Web) API Integration
Please read below for more information on how to use these two methods to access residency data from ArcGIS from within the CivicRec system.
Integration Method 1 – Manual (Periodic) Address Import
The first method involves a manual, periodic import of the addresses that the customer considers to be “resident”. During account creation, CivicRec validates the address information against its locally stored data and flags the registrant as being resident or non-resident. The addresses are kept in the CivicRec database and must be updated regularly (quarterly or annually).
There is an established format in which the address data should be sent to CivicRec. The format for this data is a simple, comma-delimited format that is structured as follows:
- Street Name – The name part of the street only. This would not include street type indicators like “St” or “Blvd”
- Street Type – “St”, “Street”, “Way”, “Blvd”, “Boulevard”, etc. The system handles the most commonly used street type abbreviations, so either an abbreviation or a full street type should both be successful
- House Number (Optional)* – The specific house number of the parcel
- Odd House Number (From) – The smallest, odd-numbered parcel on the street that is considered a resident
- Odd House Number (To) – The largest, odd-numbered parcel on the street that is considered a resident
- Even House Number (From) – The smallest, even-numbered parcel on the street that is considered a resident
- Even House Number (To) – The largest, even-numbered parcel on the street that is considered a resident
- City – The City that must be specified in conjunction with the street address to ensure the registrant is a resident
- Zip – The zip code that must be used with the house number and city to ensure the registrant is a resident
*Most files are produced with a range of addresses. If a range of addresses is supplied, the customer does NOT need to fill in the House Number field. It can be left empty in the file. The field is ONLY needed if the customer wishes to send every house number on a different line in their file.
Integration Method 2 – Live REST (Web Service) Integration
The REST integration allows for the CivicRec server to call the customer’s ArcGIS service in real-time, during account creation. The ArcGIS server will return data to CivicRec that is used to determine residency status. The registrant’s account is then flagged based on up to the minute residency data. There are a couple of advantages to this integration method:
- Residency data is always up to date
- ArcGIS has particular capabilities around parsing address information. Where CivicRec is likely to be more literal in dealing with misspellings, apartment numbers, etc, ArcGIS will be more capable in its handling of address anomalies
When using the REST API, you must know the well-known endpoint, which represents a server catalog.
For ArcGIS Server, the default endpoint is as follows:
- http://<host> is the ArcGIS Server host name.
- /<site> is the site name. The default value is "/arcgis/". ArcGIS Server accepts a site name specified in a URL as lowercase (arcgis) or camel case (ArcGIS). Using an all lower case site name is the recommended option.
- rest/services indicates the REST services endpoint. You'll see a list of all services in the root directory along with any folders. This part of the URL is case sensitive and should be specified in all lowercase.
- /<folder>: When the URL endpoint is to a folder, you'll see a list of all services included in this folder. Folder names are case sensitive and should be specified in the case as it was created.
- /<serviceName>/<serviceType> represents the name of the service and its type (for example, PopulationDensity/MapServer). The service name is case sensitive and should be specified in the case it was created.
- The service type should always be specified in a mixed case format as defined for each service in the REST API reference (for example, MapServer, GeocodeServer, GPServer).
Additional Capability of the REST API Integration
In addition to being able to search for a full address in ArcGIS, the REST api allows CivicRec to offer suggestions to the registrant to ensure that the address being entered is normalized. In other words, as a registrant (or staffer) begins to type “1234”, CivicRec can pull suggested addresses from ArcGIS like:
- "1234 Main St"
- "12347 Main St"
- "1234 Oak Avenue"
- "12345 Elm St"
This provides a user-friendly way for the registrant to ensure they are picking a fully normalized address and won’t mistakenly be marked as a non-resident because of misspellings or other extraneous data like apartment numbers.
It should be noted that this capability COULD also coach a non-resident into selecting a resident address. The customer should weigh the benefits against the risks of having CivicRec activate this capability.