Tasks: Respond to emails

Whenever a user contacts us about Represent, it's a good practice to add them as a user and to ask them how they are using it and to ask for a link to their use case, which we can use in communications and in fundraising.

A user reports an inaccurate postal code

This is the most frequent email, but there is no resolution for the error. You can write longer or shorter messages using the following information:

As written in the documentation at http://represent.opennorth.ca/api/#postcode:

Using postal codes is error prone, because a postal code can match multiple boundaries and because postal codes change constantly. For 100% accuracy, geocode addresses using the Bing, Google, MapQuest or Yahoo geocoding APIs, and then submit a latitude and longitude to the boundaries or representatives endpoints. Latitudes and longitudes never change and always match a single boundary.

It's important to be aware of the limitations of postal codes, which are primarily a way for Canada Post to sort mail, not a way to match an electoral district. We've heard from chief electoral officers across Canada that postal codes are not 100% accurate for matching an electoral district, and our own research – using the highest quality postal code data – confirms this.

Postal codes will always be inaccurate for three reasons:

1. They are constantly changing. Canada Post frequently creates new, deletes old, and reassigns postal codes, as it optimizes its mail routes. Canada Post doesn’t care that people use postal codes as a proxy for location. Postal codes are just a way to sort and route mail. When it reassigns a postal code to a new area, people may continue using the old postal code to address mail, lookup MPs, etc. Obviously, it causes problems for a postal code to be in two areas over time.

2. People in rural areas often pick up their mail in a nearby town, which may be in a different electoral district than their home address. Their home may not have a postcode, since mail isn't delivered there. They only know the postcode for the mailbox in the nearby town (which is not where they vote). The Chief Electoral Officers of Manitoba and Prince Edward Island do not offer lists of postal codes for provincial electoral boundaries, because too many mailing addresses are outside of the electoral district where the voter resides.

3. Postal codes can cross electoral boundaries.

Point #2 basically means “don’t use postal codes” if you want 100% accuracy. If we had the most accurate, up-to-date postal code data, however, we could at least solve 1 and 3. This data could be merged with electoral districts to determine a concordance. However, accurate data costs $10,000 from DMTI and $50,000 from Canada Post.

Since Open North (and our users) cannot afford that data, we instead rely on latitude-longitude data for postal codes. Relying on lat-long will be inaccurate for the postal codes that cross electoral boundaries - and we can’t be sure that the lat-long itself is accurate. At the provincial level, only Quebec offers concordances.

A user reports a discrepancy between the demo and API

The page http://represent.opennorth.ca/demo/ doesn't use the Represent API's postcodes endpoint. It instead submits any user-provided text to Google, which transforms it to a latitude and longitude. Note that Google has postcode errors.

A user will exceed the rate limit

If they are doing a one-time batch job, ask them to simply submit one request per second. If this would take too long to complete (weeks), inform them that they will be permitted to exceed the rate limit for a period.

If they are concerned than an online campaign will exceed the rate limit, explain that we only block IPs that cause a heavy load over an extended and uninterrupted period.

FYI, the server has served over a million requests in a day without a service disrupt, so a user would need to send millions of requests per day over a long period to disrupt service.

If there is reason to believe a user will disrupt the service, either the user or we may set up a dedicated server for their exclusive use. This has yet to occur. If it does, consider using this draft Service Level Agreement.

A user requests or offers representatives data for a new jurisdiction

The options in order of preference are to:

1. Request the jurisdiction to publish the data according to the Represent CSV Schema
2. Write a scraper in scrapers-ca to collect the data, in which case it is appropriate to ask the user to agree to pay a reasonable one-time fee to author and maintain the scraper
3. Ask the user to author and share a spreadsheet in Google Sheets (you can email a link to this template (French version) for them to copy) that follows the Represent CSV Schema, and then import it

The first option provides good quality data at no cost. The second option provides good quality data at some cost. The third option provides lower quality data at no cost. With Represent, we prefer not to sacrifice quality to lower cost.

A user reports incorrect data

If the scraper is broken according to the dashboard, fix it. Otherwise, review the data in Represent, and correct any errors in the scraper.

A user requests custom development

In general, we do not work with clients to build new services using the API or to integrate the API into existing systems. Instead, we refer users to consultancies in our referral program.