csvbase is a simple website for sharing table data. Join the discord.
Table of contents
The basics: auth and content negotiation
Authentication
With CSVBase, you authenticate using by putting your username and API key straight in the url (known as "HTTP "basic" auth").
Here's an example:
https://<some_user>:<some_api_key>@csvbase.com/robertbrook/candidacies-2019
Basic auth is widely supported and is usually accepted anywhere that accepts urls.
However, robertbrook/candidacies-2019 is public so auth is needed only for writes.
Content negotiation
CSVBase APIs use content negotiation to decide what formats are in use. This means it consults HTTP headers to decide what format to send back in response to a request.
It important that you set the Content-Type
and Accept headers to be the mimetype you want:
typically that is application/json for both. If you fail to
include these headers in your requests, the API will still work but
CSVBase will pick a sensible default: CSV for tables, JSON for rows.
You can bypass content negotiation for read-only requests by appending a
file extension to the url, eg .json. Here's an example
of that (same resource as above):
https://<some_user>:<some_api_key>@csvbase.com/robertbrook/candidacies-2019.json
This is useful when dealing with software where you aren't able to set headers.
The API: endpoint-by-endpoint
There are three kinds of thing in csvbase:
- users
- tables
- rows
While there's no API for users so far, there is for tables and rows.
Tables
This table looks like this in JSON:
{
"name": "candidacies-2019",
"is_public": true,
"caption": "",
"licence": null,
"created": "2024-06-25T14:09:32.725981+01:00",
"last_changed": "2024-06-25T14:09:32.725981+01:00",
"columns": [
{
"name": "csvbase_row_id",
"type": "integer"
},
{
"name": "Parliament number",
"type": "integer"
},
{
"name": "Parliament summoned on",
"type": "date"
},
{
"name": "Parliament dissolved on",
"type": "date"
},
{
"name": "Parliament Wikidata ID",
"type": "string"
},
{
"name": "Parliament London Gazette citation",
"type": "string"
},
{
"name": "Parliament URL",
"type": "string"
},
{
"name": "General election polling date",
"type": "date"
},
{
"name": "General election is notional",
"type": "boolean"
},
{
"name": "Total electorate in general election",
"type": "integer"
},
{
"name": "Total valid votes in general election",
"type": "integer"
},
{
"name": "Total invalid votes in general election",
"type": "integer"
},
{
"name": "General election URL",
"type": "string"
},
{
"name": "Country name",
"type": "string"
},
{
"name": "Country geographic code",
"type": "string"
},
{
"name": "Country URL",
"type": "string"
},
{
"name": "English region name",
"type": "string"
},
{
"name": "English region geographic code",
"type": "string"
},
{
"name": "English region URL",
"type": "string"
},
{
"name": "Constituency name",
"type": "string"
},
{
"name": "Constituency geographic code",
"type": "string"
},
{
"name": "Constituency designation",
"type": "string"
},
{
"name": "Constituency URL",
"type": "string"
},
{
"name": "Boundary set start date",
"type": "date"
},
{
"name": "Boundary set end date",
"type": "date"
},
{
"name": "Boundary set URL",
"type": "string"
},
{
"name": "Electorate",
"type": "integer"
},
{
"name": "Election polling date",
"type": "date"
},
{
"name": "Election is by-election",
"type": "boolean"
},
{
"name": "Declaration time",
"type": "string"
},
{
"name": "Election valid vote count",
"type": "integer"
},
{
"name": "Election invalid vote count",
"type": "integer"
},
{
"name": "Election URL",
"type": "string"
},
{
"name": "Election result summary",
"type": "string"
},
{
"name": "Candidate family name",
"type": "string"
},
{
"name": "Candidate given name",
"type": "string"
},
{
"name": "Candidate MNIS ID",
"type": "integer"
},
{
"name": "Candidate is sitting MP",
"type": "boolean"
},
{
"name": "Candidate is former MP",
"type": "boolean"
},
{
"name": "Candidate Member URL",
"type": "string"
},
{
"name": "Main party name",
"type": "string"
},
{
"name": "Main party abbreviation",
"type": "string"
},
{
"name": "Main party Electoral Commission ID",
"type": "string"
},
{
"name": "Main party MNIS ID",
"type": "integer"
},
{
"name": "Main party URL",
"type": "string"
},
{
"name": "Adjunct party name",
"type": "string"
},
{
"name": "Adjunct party abbreviation",
"type": "string"
},
{
"name": "Adjunct party Electoral Commission ID",
"type": "string"
},
{
"name": "Candidate is standing as Commons Speaker",
"type": "boolean"
},
{
"name": "Candidate is standing as independent",
"type": "boolean"
},
{
"name": "Candidate vote count",
"type": "integer"
},
{
"name": "Candidate vote share",
"type": "float"
},
{
"name": "Candidate vote change",
"type": "float"
},
{
"name": "Majority",
"type": "integer"
},
{
"name": "Candidate result position",
"type": "integer"
}
],
"approx_size": 3320,
"page": {
"rows": [
{
"row": {
"Parliament number": 58,
"Parliament summoned on": "2019-12-17",
"Parliament dissolved on": "2024-05-30",
"Parliament Wikidata ID": "Q77685395",
"Parliament London Gazette citation": "issue 64411",
"Parliament URL": "http://electionresults.parliament.uk/parliament-periods/58",
"General election polling date": "2019-12-12",
"General election is notional": false,
"Total electorate in general election": 47562702,
"Total valid votes in general election": 32014110,
"Total invalid votes in general election": 117919,
"General election URL": "http://electionresults.parliament.uk/general-elections/4",
"Country name": "Wales",
"Country geographic code": "W92000004",
"Country URL": "http://electionresults.parliament.uk/countries/6",
"English region name": null,
"English region geographic code": null,
"English region URL": null,
"Constituency name": "Aberavon",
"Constituency geographic code": "W07000049",
"Constituency designation": "County",
"Constituency URL": "http://electionresults.parliament.uk/constituency-areas/1",
"Boundary set start date": "2010-04-13",
"Boundary set end date": "2024-05-30",
"Boundary set URL": "http://electionresults.parliament.uk/boundary-sets/7",
"Electorate": 50750,
"Election polling date": "2019-12-12",
"Election is by-election": false,
"Declaration time": "2019-12-13 02:30:00 UTC",
"Election valid vote count": 31598,
"Election invalid vote count": 82,
"Election URL": "http://electionresults.parliament.uk/elections/1301",
"Election result summary": "Lab hold",
"Candidate family name": "Kinnock",
"Candidate given name": "Stephen",
"Candidate MNIS ID": 4359,
"Candidate is sitting MP": true,
"Candidate is former MP": true,
"Candidate Member URL": "http://electionresults.parliament.uk/members/4359",
"Main party name": "Labour",
"Main party abbreviation": "Lab",
"Main party Electoral Commission ID": "PP53",
"Main party MNIS ID": 15,
"Main party URL": "http://electionresults.parliament.uk/political-parties/3",
"Adjunct party name": null,
"Adjunct party abbreviation": null,
"Adjunct party Electoral Commission ID": null,
"Candidate is standing as Commons Speaker": false,
"Candidate is standing as independent": false,
"Candidate vote count": 17008,
"Candidate vote share": 0.538262,
"Candidate vote change": -0.142933,
"Majority": 10490,
"Candidate result position": 1
},
"row_id": 1,
"url": "https://csvbase.com/robertbrook/candidacies-2019/rows/1"
}
],
"previous_page_url": null,
"next_page_url": "https://csvbase.com/robertbrook/candidacies-2019?op=gt&n=1"
}
}
Note that there is the top-level metadata, plus a "page" of rows. Tables
are often (usually) too big to be put into a single JSON object so they
are "paginated". To follow the table, page by page, you can use
the next_page_url and previous_page_url
dictionary keys. They will be null if you've reached
the end or are at the beginning, respectively.
Reading a table
GET from https://csvbase.com/robertbrook/candidacies-2019
You'll need to follow the next_page_url urls (described
above) to get to the end of the table.
Rows
Rows from robertbrook/candidacies-2019 look like this in JSON:
{
"row": {
"Parliament number": 58,
"Parliament summoned on": "2019-12-17",
"Parliament dissolved on": "2024-05-30",
"Parliament Wikidata ID": "Q77685395",
"Parliament London Gazette citation": "issue 64411",
"Parliament URL": "http://electionresults.parliament.uk/parliament-periods/58",
"General election polling date": "2019-12-12",
"General election is notional": false,
"Total electorate in general election": 47562702,
"Total valid votes in general election": 32014110,
"Total invalid votes in general election": 117919,
"General election URL": "http://electionresults.parliament.uk/general-elections/4",
"Country name": "Wales",
"Country geographic code": "W92000004",
"Country URL": "http://electionresults.parliament.uk/countries/6",
"English region name": null,
"English region geographic code": null,
"English region URL": null,
"Constituency name": "Aberavon",
"Constituency geographic code": "W07000049",
"Constituency designation": "County",
"Constituency URL": "http://electionresults.parliament.uk/constituency-areas/1",
"Boundary set start date": "2010-04-13",
"Boundary set end date": "2024-05-30",
"Boundary set URL": "http://electionresults.parliament.uk/boundary-sets/7",
"Electorate": 50750,
"Election polling date": "2019-12-12",
"Election is by-election": false,
"Declaration time": "2019-12-13 02:30:00 UTC",
"Election valid vote count": 31598,
"Election invalid vote count": 82,
"Election URL": "http://electionresults.parliament.uk/elections/1301",
"Election result summary": "Lab hold",
"Candidate family name": "Kinnock",
"Candidate given name": "Stephen",
"Candidate MNIS ID": 4359,
"Candidate is sitting MP": true,
"Candidate is former MP": true,
"Candidate Member URL": "http://electionresults.parliament.uk/members/4359",
"Main party name": "Labour",
"Main party abbreviation": "Lab",
"Main party Electoral Commission ID": "PP53",
"Main party MNIS ID": 15,
"Main party URL": "http://electionresults.parliament.uk/political-parties/3",
"Adjunct party name": null,
"Adjunct party abbreviation": null,
"Adjunct party Electoral Commission ID": null,
"Candidate is standing as Commons Speaker": false,
"Candidate is standing as independent": false,
"Candidate vote count": 17008,
"Candidate vote share": 0.538262,
"Candidate vote change": -0.142933,
"Majority": 10490,
"Candidate result position": 1
},
"row_id": 1,
"url": "https://csvbase.com/robertbrook/candidacies-2019/rows/1"
}
Creating a new row
POST to https://<some_user>:<some_api_key>@csvbase.com/robertbrook/candidacies-2019/rows/
Example body
{
"row": {
"Parliament number": 58,
"Parliament summoned on": "2019-12-17",
"Parliament dissolved on": "2024-05-30",
"Parliament Wikidata ID": "Q77685395",
"Parliament London Gazette citation": "issue 64411",
"Parliament URL": "http://electionresults.parliament.uk/parliament-periods/58",
"General election polling date": "2019-12-12",
"General election is notional": false,
"Total electorate in general election": 47562702,
"Total valid votes in general election": 32014110,
"Total invalid votes in general election": 117919,
"General election URL": "http://electionresults.parliament.uk/general-elections/4",
"Country name": "Wales",
"Country geographic code": "W92000004",
"Country URL": "http://electionresults.parliament.uk/countries/6",
"English region name": null,
"English region geographic code": null,
"English region URL": null,
"Constituency name": "Aberavon",
"Constituency geographic code": "W07000049",
"Constituency designation": "County",
"Constituency URL": "http://electionresults.parliament.uk/constituency-areas/1",
"Boundary set start date": "2010-04-13",
"Boundary set end date": "2024-05-30",
"Boundary set URL": "http://electionresults.parliament.uk/boundary-sets/7",
"Electorate": 50750,
"Election polling date": "2019-12-12",
"Election is by-election": false,
"Declaration time": "2019-12-13 02:30:00 UTC",
"Election valid vote count": 31598,
"Election invalid vote count": 82,
"Election URL": "http://electionresults.parliament.uk/elections/1301",
"Election result summary": "Lab hold",
"Candidate family name": "Kinnock",
"Candidate given name": "Stephen",
"Candidate MNIS ID": 4359,
"Candidate is sitting MP": true,
"Candidate is former MP": true,
"Candidate Member URL": "http://electionresults.parliament.uk/members/4359",
"Main party name": "Labour",
"Main party abbreviation": "Lab",
"Main party Electoral Commission ID": "PP53",
"Main party MNIS ID": 15,
"Main party URL": "http://electionresults.parliament.uk/political-parties/3",
"Adjunct party name": null,
"Adjunct party abbreviation": null,
"Adjunct party Electoral Commission ID": null,
"Candidate is standing as Commons Speaker": false,
"Candidate is standing as independent": false,
"Candidate vote count": 17008,
"Candidate vote share": 0.538262,
"Candidate vote change": -0.142933,
"Majority": 10490,
"Candidate result position": 1
}
}
Example response
{
"row": {
"Parliament number": 58,
"Parliament summoned on": "2019-12-17",
"Parliament dissolved on": "2024-05-30",
"Parliament Wikidata ID": "Q77685395",
"Parliament London Gazette citation": "issue 64411",
"Parliament URL": "http://electionresults.parliament.uk/parliament-periods/58",
"General election polling date": "2019-12-12",
"General election is notional": false,
"Total electorate in general election": 47562702,
"Total valid votes in general election": 32014110,
"Total invalid votes in general election": 117919,
"General election URL": "http://electionresults.parliament.uk/general-elections/4",
"Country name": "Wales",
"Country geographic code": "W92000004",
"Country URL": "http://electionresults.parliament.uk/countries/6",
"English region name": null,
"English region geographic code": null,
"English region URL": null,
"Constituency name": "Aberavon",
"Constituency geographic code": "W07000049",
"Constituency designation": "County",
"Constituency URL": "http://electionresults.parliament.uk/constituency-areas/1",
"Boundary set start date": "2010-04-13",
"Boundary set end date": "2024-05-30",
"Boundary set URL": "http://electionresults.parliament.uk/boundary-sets/7",
"Electorate": 50750,
"Election polling date": "2019-12-12",
"Election is by-election": false,
"Declaration time": "2019-12-13 02:30:00 UTC",
"Election valid vote count": 31598,
"Election invalid vote count": 82,
"Election URL": "http://electionresults.parliament.uk/elections/1301",
"Election result summary": "Lab hold",
"Candidate family name": "Kinnock",
"Candidate given name": "Stephen",
"Candidate MNIS ID": 4359,
"Candidate is sitting MP": true,
"Candidate is former MP": true,
"Candidate Member URL": "http://electionresults.parliament.uk/members/4359",
"Main party name": "Labour",
"Main party abbreviation": "Lab",
"Main party Electoral Commission ID": "PP53",
"Main party MNIS ID": 15,
"Main party URL": "http://electionresults.parliament.uk/political-parties/3",
"Adjunct party name": null,
"Adjunct party abbreviation": null,
"Adjunct party Electoral Commission ID": null,
"Candidate is standing as Commons Speaker": false,
"Candidate is standing as independent": false,
"Candidate vote count": 17008,
"Candidate vote share": 0.538262,
"Candidate vote change": -0.142933,
"Majority": 10490,
"Candidate result position": 1
},
"row_id": 1,
"url": "https://csvbase.com/robertbrook/candidacies-2019/rows/1"
}
Status code 201 upon success.
Reading a row
GET from https://csvbase.com/robertbrook/candidacies-2019/rows/1
No body is provided with this request. Status code 200 upon success.
Example response
{
"row": {
"Parliament number": 58,
"Parliament summoned on": "2019-12-17",
"Parliament dissolved on": "2024-05-30",
"Parliament Wikidata ID": "Q77685395",
"Parliament London Gazette citation": "issue 64411",
"Parliament URL": "http://electionresults.parliament.uk/parliament-periods/58",
"General election polling date": "2019-12-12",
"General election is notional": false,
"Total electorate in general election": 47562702,
"Total valid votes in general election": 32014110,
"Total invalid votes in general election": 117919,
"General election URL": "http://electionresults.parliament.uk/general-elections/4",
"Country name": "Wales",
"Country geographic code": "W92000004",
"Country URL": "http://electionresults.parliament.uk/countries/6",
"English region name": null,
"English region geographic code": null,
"English region URL": null,
"Constituency name": "Aberavon",
"Constituency geographic code": "W07000049",
"Constituency designation": "County",
"Constituency URL": "http://electionresults.parliament.uk/constituency-areas/1",
"Boundary set start date": "2010-04-13",
"Boundary set end date": "2024-05-30",
"Boundary set URL": "http://electionresults.parliament.uk/boundary-sets/7",
"Electorate": 50750,
"Election polling date": "2019-12-12",
"Election is by-election": false,
"Declaration time": "2019-12-13 02:30:00 UTC",
"Election valid vote count": 31598,
"Election invalid vote count": 82,
"Election URL": "http://electionresults.parliament.uk/elections/1301",
"Election result summary": "Lab hold",
"Candidate family name": "Kinnock",
"Candidate given name": "Stephen",
"Candidate MNIS ID": 4359,
"Candidate is sitting MP": true,
"Candidate is former MP": true,
"Candidate Member URL": "http://electionresults.parliament.uk/members/4359",
"Main party name": "Labour",
"Main party abbreviation": "Lab",
"Main party Electoral Commission ID": "PP53",
"Main party MNIS ID": 15,
"Main party URL": "http://electionresults.parliament.uk/political-parties/3",
"Adjunct party name": null,
"Adjunct party abbreviation": null,
"Adjunct party Electoral Commission ID": null,
"Candidate is standing as Commons Speaker": false,
"Candidate is standing as independent": false,
"Candidate vote count": 17008,
"Candidate vote share": 0.538262,
"Candidate vote change": -0.142933,
"Majority": 10490,
"Candidate result position": 1
},
"row_id": 1,
"url": "https://csvbase.com/robertbrook/candidacies-2019/rows/1"
}
Updating an existing row
PUT to https://<some_user>:<some_api_key>@csvbase.com/robertbrook/candidacies-2019/rows/1
Example body
{
"row": {
"Parliament number": 58,
"Parliament summoned on": "2019-12-17",
"Parliament dissolved on": "2024-05-30",
"Parliament Wikidata ID": "Q77685395",
"Parliament London Gazette citation": "issue 64411",
"Parliament URL": "http://electionresults.parliament.uk/parliament-periods/58",
"General election polling date": "2019-12-12",
"General election is notional": false,
"Total electorate in general election": 47562702,
"Total valid votes in general election": 32014110,
"Total invalid votes in general election": 117919,
"General election URL": "http://electionresults.parliament.uk/general-elections/4",
"Country name": "Wales",
"Country geographic code": "W92000004",
"Country URL": "http://electionresults.parliament.uk/countries/6",
"English region name": null,
"English region geographic code": null,
"English region URL": null,
"Constituency name": "Aberavon",
"Constituency geographic code": "W07000049",
"Constituency designation": "County",
"Constituency URL": "http://electionresults.parliament.uk/constituency-areas/1",
"Boundary set start date": "2010-04-13",
"Boundary set end date": "2024-05-30",
"Boundary set URL": "http://electionresults.parliament.uk/boundary-sets/7",
"Electorate": 50750,
"Election polling date": "2019-12-12",
"Election is by-election": false,
"Declaration time": "2019-12-13 02:30:00 UTC",
"Election valid vote count": 31598,
"Election invalid vote count": 82,
"Election URL": "http://electionresults.parliament.uk/elections/1301",
"Election result summary": "Lab hold",
"Candidate family name": "Kinnock",
"Candidate given name": "Stephen",
"Candidate MNIS ID": 4359,
"Candidate is sitting MP": true,
"Candidate is former MP": true,
"Candidate Member URL": "http://electionresults.parliament.uk/members/4359",
"Main party name": "Labour",
"Main party abbreviation": "Lab",
"Main party Electoral Commission ID": "PP53",
"Main party MNIS ID": 15,
"Main party URL": "http://electionresults.parliament.uk/political-parties/3",
"Adjunct party name": null,
"Adjunct party abbreviation": null,
"Adjunct party Electoral Commission ID": null,
"Candidate is standing as Commons Speaker": false,
"Candidate is standing as independent": false,
"Candidate vote count": 17008,
"Candidate vote share": 0.538262,
"Candidate vote change": -0.142933,
"Majority": 10490,
"Candidate result position": 1
},
"row_id": 1,
"url": "https://csvbase.com/robertbrook/candidacies-2019/rows/1"
}
Response
Upon success the body you sent will be echoed back, with status code 200.
Deleting a row
DELETE from https://<some_user>:<some_api_key>@csvbase.com/robertbrook/candidacies-2019/rows/1
No body is required. Status code 204 upon success.