Developer Resources
Manage your API access and explore the documentation.
Petitions API Documentation
Access Canadian parliamentary petition data programmatically via the MyParliament GraphQL API.
This API provides read access to all petitions from the 45th Canadian Parliament. An API key is required for all requests. Generate your key from the API Dashboard tab above.
Authentication
All API requests require an API key passed via the Authorization header using the Bearer scheme. Generate your API key from the API Dashboard.
http
Authorization: Bearer mp_live_your_api_key_here
Getting your API key
1. Sign in to MyParliament. 2. Navigate to the API Dashboard tab above. 3. Click "Generate API Key". 4. Copy and securely store your key — it is only shown once.
Keep your API key secret. Do not expose it in client-side code, public repositories, or browser-accessible files. If your key is compromised, revoke it immediately from the dashboard and generate a new one.
Rate Limits
API requests are rate-limited per API key to ensure fair usage. Current limits are:
| Limit | Value | Window |
|---|---|---|
Requests per minute | 20 | Sliding 60s window |
Requests per day | 500 | Sliding 24h window |
Rate limit headers
Every response includes rate limit information in the headers:
| Parameter | Type | Required | Description |
|---|---|---|---|
X-RateLimit-Limit | Integer | No | Maximum requests allowed in the current window |
X-RateLimit-Remaining | Integer | No | Requests remaining in the current window |
X-RateLimit-Reset | ISO 8601 | No | Timestamp when the rate limit window resets |
Retry-After | Integer | No | Seconds to wait before retrying (only on 429 responses) |
If you need higher rate limits for a production application, contact us — we can adjust limits on a case-by-case basis.
Endpoint
The API exposes a single GraphQL endpoint. All queries are sent as HTTP POST requests with a JSON body containing the query and optionally variables.
https://myparliament.ca/api/graphql/v1
Request format
| Parameter | Type | Required | Description |
|---|---|---|---|
query | String | Yes | The GraphQL query string |
variables | Object | No | Optional variables map for parameterised queries |
operationName | String | No | Optional name of the operation to execute |
cURL example
bash
curl -X POST https://myparliament.ca/api/graphql/v1 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer mp_live_your_api_key_here" \
-d '{
"query": "query { petitions(page: 1, pageSize: 5, sortBy: SIGNATURE_COUNT, sortOrder: DESC) { items { id petitionNumber subject signatureCount statusName } pagination { total hasNextPage } } }"
}'Query: petitions
Returns a paginated list of petitions, optionally filtered and sorted.
Arguments
| Parameter | Type | Required | Description |
|---|---|---|---|
page | Int | No | Page number, 1-indexed (default: 1) |
pageSize | Int | No | Results per page, max 100 (default: 50) |
filters | PetitionFiltersInput | No | Filter criteria — see Filters section |
sortBy | PetitionSortField | No | Field to sort by (default: SIGNATURE_COUNT) — see Enums |
sortOrder | SortOrder | No | ASC or DESC (default: DESC) |
Returns
A PetitionConnection with items (array of Petition) and pagination metadata.
Example query
graphql
query GetPetitions {
petitions(
page: 1
pageSize: 10
sortBy: SIGNATURE_COUNT
sortOrder: DESC
filters: {
isEpetition: true
statusName: "Open for signature"
}
) {
items {
id
petitionNumber
subject
statusName
signatureCount
isEpetition
mpName
mpCaucus
dateOpened
dateClosed
provinceSignatures {
province
signatureCount
}
}
pagination {
page
pageSize
total
totalPages
hasNextPage
hasPreviousPage
}
}
}Query: petition
Retrieves a single petition by its numeric database ID.
Arguments
| Parameter | Type | Required | Description |
|---|---|---|---|
id | Int! | Yes | The numeric petition ID (e.g. 13583047). This is the internal database ID, not the petition number like e-6722. |
Returns
A single Petition object, or null if not found.
Example query
graphql
query GetPetition {
petition(id: 13583047) {
id
petitionNumber
subject
statusName
signatureCount
request
governmentResponseText
responseDate
mpName
mpConstituency
mpCaucus
mpProvinceCode
parliamentNumber
sessionId
typeId
isEpetition
dateOpened
dateClosed
dateCertified
datePresented
provinceSignatures {
province
signatureCount
}
}
}Types
Petition
| Field | Type | Nullable | Description |
|---|---|---|---|
id | Int! | No | Internal numeric database ID |
petitionNumber | String! | No | Human-readable petition number, e.g. "e-6722" or "451-00532" |
sessionId | Int! | No | Parliamentary session number |
parliamentNumber | Int! | No | Parliament number (e.g. 45) |
typeId | Int! | No | Raw type identifier: 81830 = e-petition, 19 = paper petition |
isEpetition | Boolean! | No | Convenience flag — true for e-petitions, false for paper petitions |
statusId | Int! | No | Internal status code |
statusName | String! | No | Human-readable status, e.g. "Open for signature", "Government response tabled" |
subject | String! | No | Petition subject / title |
request | String! | No | Full petition text with \n\n paragraph breaks |
signatureCount | Int! | No | Total signatures at time of last import |
dateOpened | String | Yes | ISO 8601 datetime when the petition opened for signatures (e-petitions only) |
dateClosed | String | Yes | ISO 8601 datetime when the petition closed for signatures |
dateCertified | String | Yes | ISO 8601 date when the petition was certified |
datePresented | String | Yes | ISO 8601 date when the petition was presented to the House |
responseDate | String | Yes | ISO 8601 date when the government response was tabled |
governmentResponseText | String | Yes | Full text of the government response, if tabled |
mpName | String! | No | Full name of the sponsoring MP |
mpConstituency | String! | No | Riding name of the sponsoring MP |
mpCaucus | String! | No | Caucus/party of the sponsor, e.g. "Conservative", "Liberal", "NDP" |
mpProvinceCode | String! | No | Two-letter province code of the sponsor, e.g. "ON", "BC" |
provinceSignatures | [PetitionProvinceSignature!]! | No | Signature counts by province. Empty array for paper petitions. |
createdAt | String! | No | ISO 8601 datetime when this record was first imported |
updatedAt | String! | No | ISO 8601 datetime of the most recent import update |
PetitionProvinceSignature
| Field | Type | Nullable | Description |
|---|---|---|---|
province | String! | No | Province or territory name, e.g. "Ontario", "British Columbia". May also be "Other Countries". |
signatureCount | Int! | No | Number of signatures from this province |
PetitionConnection
| Field | Type | Nullable | Description |
|---|---|---|---|
items | [Petition!]! | No | The petitions for the current page |
pagination | PaginationMeta! | No | Pagination metadata |
PaginationMeta
| Field | Type | Nullable | Description |
|---|---|---|---|
page | Int! | No | Current page number |
pageSize | Int! | No | Number of results per page |
total | Int! | No | Total number of matching records |
totalPages | Int! | No | Total number of pages |
hasNextPage | Boolean! | No | Whether a next page exists |
hasPreviousPage | Boolean! | No | Whether a previous page exists |
Filters & Enums
PetitionFiltersInput
All fields are optional and combined with AND logic. String filters use case-insensitive matching unless otherwise noted.
| Parameter | Type | Required | Description |
|---|---|---|---|
search | String | No | Full-text search across subject, request body, petition number, and MP name |
statusName | String | No | Case-insensitive partial match on status, e.g. "Open" or "response tabled" |
sessionId | Int | No | Filter by parliamentary session number |
parliamentNumber | Int | No | Filter by parliament number, e.g. 45 |
isEpetition | Boolean | No | true = e-petitions only, false = paper petitions only |
typeId | Int | No | Raw type ID. Overrides isEpetition if both are provided. |
mpName | String | No | Case-insensitive partial match on sponsor MP name |
mpConstituency | String | No | Case-insensitive partial match on sponsor riding name |
mpCaucus | String | No | Case-insensitive exact match on caucus, e.g. "Conservative" |
mpProvinceCode | String | No | Case-insensitive exact match on province code, e.g. "ON" |
province | String | No | Return only petitions with at least one signature from this province |
PetitionSortField (enum)
| Value | Description |
|---|---|
SIGNATURE_COUNT | Sort by total signature count (default) |
DATE_OPENED | Sort by petition open date |
DATE_CLOSED | Sort by petition close date |
DATE_CERTIFIED | Sort by certification date |
DATE_PRESENTED | Sort by date presented to House |
RESPONSE_DATE | Sort by government response date |
PETITION_NUMBER | Sort by petition number alphanumerically |
CREATED_AT | Sort by import creation date |
SortOrder (enum)
| Value | Description |
|---|---|
ASC | Ascending order |
DESC | Descending order (default) |
Examples
Fetch open e-petitions sorted by popularity
graphql
query OpenEpetitions {
petitions(
page: 1
pageSize: 20
sortBy: SIGNATURE_COUNT
sortOrder: DESC
filters: { isEpetition: true, statusName: "Open" }
) {
items { petitionNumber subject signatureCount dateClosed }
pagination { total hasNextPage }
}
}Filter by sponsoring party
graphql
query NdpPetitions {
petitions(
filters: { mpCaucus: "NDP" }
sortBy: DATE_PRESENTED
sortOrder: DESC
) {
items { petitionNumber subject mpName mpConstituency statusName }
pagination { total }
}
}Find petitions with signatures from Quebec
graphql
query QuebecPetitions {
petitions(
filters: { province: "Quebec" }
sortBy: SIGNATURE_COUNT
sortOrder: DESC
) {
items {
petitionNumber
subject
signatureCount
provinceSignatures { province signatureCount }
}
pagination { total }
}
}Full-text search
graphql
query SearchPetitions {
petitions(
filters: { search: "climate change" }
sortBy: SIGNATURE_COUNT
sortOrder: DESC
) {
items { petitionNumber subject signatureCount statusName mpCaucus }
pagination { total }
}
}Example response
json
{
"data": {
"petitions": {
"items": [
{
"id": 13699521,
"petitionNumber": "e-6903",
"subject": "e-6903 (Citizenship and immigration)",
"signatureCount": 2275,
"statusName": "Government response tabled"
}
],
"pagination": {
"page": 1,
"pageSize": 5,
"total": 688,
"totalPages": 138,
"hasNextPage": true,
"hasPreviousPage": false
}
}
}
}Example response headers
http
HTTP/1.1 200 OK Content-Type: application/json X-RateLimit-Limit: 60 X-RateLimit-Remaining: 58 X-RateLimit-Reset: 2025-03-01T12:01:00.000Z X-Response-Time: 127ms Access-Control-Allow-Origin: *
Error Handling
GraphQL errors are returned with HTTP status 200 in the standard errors array. HTTP-level errors are returned with appropriate 4xx/5xx status codes.
GraphQL error shape
json
{
"errors": [
{
"message": "Variable \"$id\" of required type \"Int!\" was not provided.",
"locations": [{ "line": 1, "column": 16 }],
"path": null
}
],
"data": null
}Rate limit error (429)
json
{
"errors": [
{
"message": "Rate limit exceeded. Try again in 42 seconds.",
"extensions": {
"code": "RATE_LIMITED",
"status": 429
}
}
]
}HTTP status codes
| Status | Meaning |
|---|---|
200 | Success — check the errors array for GraphQL-level errors |
400 | Bad request — malformed JSON body or missing query field |
401 | Unauthorized — missing or invalid API key |
403 | Forbidden — API key revoked or expired |
429 | Too many requests — rate limit exceeded. Check Retry-After header |
502 | Bad gateway — invalid response from upstream service |
503 | Upstream GraphQL service temporarily unavailable |
504 | Gateway timeout — upstream service did not respond in time |
Data is sourced from the Parliament of Canada and updated periodically. Signature counts and petition statuses reflect the most recent import and may not be real-time.
MyParliament Developer API · Data sourced from the Parliament of Canada · myparliament.ca
Sign In Required
You need to be signed in to generate and manage API keys. Create a free account to get started.