
Guideline 20 encourages governments to offer application programming interfaces so software can search, retrieve and sometimes submit public information automatically, alongside the full bulk downloads that remain the baseline.
APIs turned open data from a set of files into something applications could build on: transit trackers, permit lookups, service-request maps. The guideline is careful, though, to treat APIs as a complement to bulk data rather than a replacement.
What the guideline means
An application programming interface lets a program ask a government database a question and receive a structured answer: the next bus arrival, the status of a building permit, the latest 311 requests in a neighborhood. Guideline 20 asks open data policies to support APIs where they add value, and to design them with input from both technical staff and the people likely to use them.
The guideline sits directly after bulk data (Guideline 19) for a reason. An API returns slices; a bulk file returns the whole. Policies that require APIs but not bulk access leave analysts reconstructing datasets one request at a time.
Model policy language patterns
Paraphrased versions of API provisions include:
- Datasets shall be published in a form that permits automated processing and shall use appropriate technology to notify the public of updates.
- Departments may publish through the central portal or through other technical means, such as programmatic interfaces, where appropriate.
- The portal shall provide machine-readable access suitable for developers, with documentation.
- An oversight body shall set technical standards that govern interfaces as well as files.
Where it appears in adopted policies
API-related language appears in several policies in this index:
- New York City's 2012 Local Law 11 required that public data sets be in a format permitting automated processing, under technical standards issued by the city.
- Boston, MA (2014) allowed departments to publish through the portal or other appropriate technical means.
- Honolulu, HI (2013), Minneapolis, MN (2014), Naperville, IL (2016) and Washington, DC (2014) also include API or automated-access provisions.
Useful background from the period includes the U.S. 18F API standards and New York City's developer portal, linked in the sources.
Common pitfalls
- API without bulk. The most frequent mistake: a polished interface with no way to download the full dataset.
- Mandatory keys and tight rate limits. Registration requirements and aggressive throttling undercut the idea of non-discriminatory access (Guideline 10).
- Unversioned endpoints. Changing an API without notice breaks every application built on it.
- Building for no one. Interfaces designed without consulting likely users often expose the wrong fields or the wrong granularity.
A practical checklist for API provisions
- Treat APIs as an addition to bulk downloads, never a substitute.
- Publish documentation, example queries and change notices for every interface.
- Keep basic access free and anonymous; if keys are used for heavy usage, issue them instantly.
- Version endpoints so existing applications keep working when the interface changes.
- Consult likely users, including developers, journalists and researchers, before deciding which fields and filters to expose.
- Monitor usage and report it, so investment follows demand.
What APIs teach about the value of operational data
In the private sector, the API-versus-bulk distinction maps neatly onto two kinds of data products. Live feeds are valuable to applications; historical extracts are valuable to model builders. Most AI and machine-learning buyers want the latter first: a full, de-identified history they can train and test against. A recurring feed can come later, once the historical set has proven useful.
If your business runs on systems that already expose data through APIs (field-service tools, POS, scheduling or telematics platforms), that plumbing makes producing a consistent extract easier. Sell my data explains the process by source system, and how to value my data covers what drives price.
We never take HIPAA/PHI data or personal customer data. Everything is de-identified before it leaves your control.
Frequently asked questions
Do open data policies require APIs?
Some do, many do not. The guideline encourages APIs where they meet real user needs, but treats bulk downloads as the baseline. Several policies instead require formats that permit automated processing and leave interface decisions to technical standards issued later.
Why shouldn't an API replace bulk downloads?
APIs return limited slices of data per request and are subject to rate limits and outages. Anyone who needs the full dataset, for research or analysis, would have to make thousands of calls and stitch the results together. Offering both serves both kinds of users.
Should public APIs require registration?
Optional keys for higher usage tiers are common, but requiring identification for basic access conflicts with the principle of non-discriminatory, anonymous access. If keys are used, they should be free, instant and not tied to restrictive terms.
Policies in the index that reflect guideline 20
| Place | Adopted | Instrument | Guidelines |
|---|---|---|---|
| New York, NY | Mar 7, 2012 | Local law (Local Law 11 of 2012) | 14578101118 |
| Honolulu, HI | Nov 27, 2013 | Ordinance | 237810111820 |
| Boston, MA | Apr 7, 2014 | Executive order | 3891318202425 |
| Washington, DC | Jul 21, 2014 | Executive directive (Mayor's Order 2014-170) | 12356789 |
| Minneapolis, MN | Aug 1, 2014 | Council-adopted policy | 34568131819 |
| San Diego, CA | Nov 24, 2014 | Administrative policy | 45818202427 |
| Suffolk County, NY | Jul 31, 2015 | Administrative policy | 78131820222426 |
| Bellevue, WA | Aug 1, 2016 | Management policy | 15678101118 |
| Naperville, IL | Nov 15, 2016 | Council resolution | 45789101112 |
Sources
Updated December 31, 2024.