Open311 and standards-based interfaces for service requests

Reference article · 6 min read

Most local governments run some form of service request system: potholes, missed collection, graffiti, streetlight outages, code complaints. The products differ, but the traffic in and out of them is the same everywhere. Residents want to report something from whatever app they already use. Council offices want a list of open items by district. A regional planning group wants comparable counts across a dozen jurisdictions. Left to itself, each of those needs becomes a separate integration project, quoted separately.

Open311 GeoReport v2 is a small, stable HTTP interface designed for exactly this traffic. It is an open specification for non-emergency service requests, published by the Open311 community and implemented by a number of commercial and open source constituent relationship management products. It is not a CRM and not a replacement for 911 or computer-aided dispatch. It is a documented doorway into the system you already bought, and the main reason to care about it is that the doorway belongs to the standard rather than to the vendor.

What GeoReport v2 actually specifies

The specification is deliberately small. An agency endpoint typically offers:

• Service list. A GET on the services resource returns the request types the jurisdiction accepts, each with a service code, name, description, optional group, and a flag indicating whether the type has additional questions attached.
• Service definition. A GET on a single service code returns those additional questions: field names, data types, required flags, and picklist values. This is how a third-party app can render your "missed collection" form correctly without anyone hand-coding it.
• Create a request. A POST to the requests resource with a service code, a location expressed as coordinates or an address, a description, optional contact fields, optional media, and any service-specific attributes.
• Read requests. A GET on the requests resource with filters such as service code, status, and date range, plus a GET for a single request by identifier.
• Token lookup. When intake is queued and no permanent identifier is issued at submission time, the POST returns a token that can later be exchanged for the real service request identifier.
• Discovery. A discovery document advertises endpoint URLs, supported formats, whether an API key is required, and which endpoints are test versus production.

Responses are JSON or XML. A jurisdiction identifier parameter allows one host to serve several jurisdictions, which matters for counties and shared service arrangements.

What the agency gets out of exposing one

The value is not the API itself. It is what stops being a project.

• Third-party reporting apps and neighborhood portals write into your system of record instead of sending email to a general inbox that someone rekeys.
• Regional dashboards become feasible because participating jurisdictions publish comparable structures, not because everyone bought the same product.
• Vendor replacement gets cheaper. When the interface is in the contract, migration means repointing consumers rather than rebuilding every integration. That is leverage at renewal even if you never switch.
• Internal reuse improves. GIS, open data publishing, and analytics can pull from a documented interface instead of a nightly custom extract that breaks after upgrades.
• Alternate front ends for accessibility, additional languages, or kiosk and call center use can be built without touching the core system.

Keys, rate limits, and abuse on an open endpoint

A public write endpoint is a front door, and it should be operated like one.

• API keys. The specification contemplates a key for submissions. Issue a separate key per application rather than one shared key, so you can revoke a misbehaving consumer without breaking everyone else. Treat the key as identity and metering, not as authorization to see restricted data.
• Personal information. Decide explicitly which fields appear in public reads. Requester name, phone, and email generally should not. Public records obligations vary by state and change over time, so confirm the treatment of submitted contact details and photographs with your counsel and records officer.
• Rate limits. Publish them. Apply separate limits to reads and writes, return a standard rate limit response rather than a silent failure, and keep a higher limit available for an integration you sanction.
• Spam and duplicates. Put human verification or app attestation at the submitting application, detect duplicates by service type plus location plus time window, and hold free text and uploaded media in a moderation queue where policy requires. Scan and size-limit uploads.
• Monitoring. Log submissions by key, alert on volume anomalies, and rehearse how you would disable a key at two in the morning.

Mapping your statuses to the standard

GeoReport v2 keeps status intentionally coarse: requests are open or closed, with a free-text status note carrying the detail. Agencies with richer internal workflows, such as received, assigned, scheduled, deferred, duplicate, and completed, need a deliberate crosswalk rather than an accidental one. Write it down, publish it alongside the endpoint, and keep the notes consistent, so a request closed as a duplicate does not read the same as a completed repair. Use the expected date field for service commitments and the responsible agency and service notice fields to tell residents who owns the work. If you add a non-standard extension field, make sure nothing breaks for consumers that ignore it.

What to write into a solicitation

Vendors frequently support the standard and still charge for it as custom integration work. The remedy is specificity in the requirements.

1. Require GeoReport v2 support as base functionality, at no separate license, module, or per-integration fee, in both a production and a test environment.
2. Require the full endpoint set, including submission, service definitions with attributes, and the discovery document, in JSON at minimum.
3. Require documented rate limits and an agency-controlled process for issuing and revoking keys.
4. Require published documentation and a sandbox available during acceptance testing, not after go-live.
5. Make an acceptance test explicit: a scripted exercise that creates a request through the API, retrieves it, sees a status change, and confirms the request appears in the agency user interface.
6. Address contract end. State that the interface remains available through transition and that exported data retains the identifiers used by the API.

Useful questions at demonstration: how do you map internal statuses, which fields do you suppress on public reads, who issues keys, what abuse controls exist, and which other jurisdictions run this endpoint in production today.

How to start

If you already own a system, ask the vendor whether the interface exists and simply is not enabled. Stand it up in test, point a small consumer at it, and publish the discovery document and status crosswalk. If a procurement is upcoming, put the requirements above into the specification rather than a preference statement, and score them. The standard is stable and modest in scope, which is the point: it is easier to require than to rebuild later.

HQT works with state and local agencies on systems engineering and software integration, including standards-based interfaces to existing service request platforms.

Frequently asked questions