API documentation

All OPDB data is available through a REST JSON API. You can query for data about specific machines, retrieve exports of the entire dataset or even use specialized endpoints for typeahead searching.

Not finding what you need? Let us know what API endpoints you would like to see added.

Authentication

Every API endpoint with the exception of typeahead searching requires authentication. In practice it means you must:

When making API request you must include an api_token parameter in your request.

Parsing OPDB IDs

A common task when interacting with the OPDB API is to parse an OPDB ID into it's separate parts. The following regular expression can be used to parse OPDB IDs

/^G([a-zA-Z0-9]+)(?:-M([a-zA-Z0-9]+)(?:-A([a-zA-Z0-9]+))?)?$/

The first capturing group will contain the group identifier, the second the machine identifier and the third the alias identifier.

Search endpoints

Typeahead search

https://opdb.org/api/search/typeahead

Very simple search interface meant to be used for typeahead searching. This endpoint does not require authentication and CORS is enabled. You can call this endpoint directly from your JavaScript code/domain. It will only return machines that have an OPDB id assigned (i.e. machines with a machine group). If you use the Select2 typeahead component the data is returned in the format Select2 expects

Parameter	Description
`api_token`	Not required! Do not include!
`q`	Required. Your search query
`include_groups`	Boolean. Set to `1` to search groups. Defaults to `0` (don't search groups)
`include_aliases`	Boolean. Set to `0` to avoid searching aliases. Defaults to `1` (do search aliases)

Search machines

https://opdb.org/api/search

Full featured search that will return full machine data in the results.

Parameter	Description
`api_token`	Required. Your API token.
`q`	Required. Your search query
`require_opdb`	Boolean. Whether to only search machines with OPDB ids. Defaults to `1` (limit searches to machines with OPDB ids)
`include_groups`	Boolean. Set to `1` to search groups. Defaults to `0` (don't search groups)
`include_aliases`	Boolean. Set to `0` to avoid searching aliases. Defaults to `1` (do search aliases)
`include_grouping_entries`	Boolean. Set to `1` to searching grouping entries that do not represent physical machines. Defaults to `0` (don't search grouping entries)

Machine endpoints

Get machine info

https://opdb.org/api/machines/{opdb_id}

Get information about a machine, machine alias or machine group.

Parameter	Description
`api_token`	Required. Your API token.
`opdb_id`	OPDB ID of the resource you seek info about

Get machine info by IPDB ID

https://opdb.org/api/machines/ipdb/{ipdb_id}

Get information about a machine based on its ID from the Internet Pinball Database (IPDB).

Parameter	Description
`api_token`	Required. Your API token.
`ipdb_id`	IPDB ID of the resource you seek info about

Export endpoints

Export machines and aliases

https://opdb.org/api/export

Export all machines and aliases as a single JSON document. Note: This endpoint is rate limited and you will only be able to request the export once per hour.

Parameter	Description
`api_token`	Required. Your API token.

Export machine groups

https://opdb.org/api/export/groups

Export all machine groups as a single JSON document.

Parameter	Description
`api_token`	Required. Your API token.

Changelog endpoints

View OPDB IDchangelog

https://opdb.org/api/changelog

View a log of all OPDB IDs that have been deleted or moved along with the replacement OPDB ID (if any). Use this to update your database with new OPDB IDs. View changelog online.

Parameter	Description
`api_token`	Not required! Do not include!
`from`	Optional. Timestamp in the format `YYYY-MM-DD hh:mm:ss`. If provided you will only receive changelog entries on or after this date. Use this to limit the response to entries you have not already seen.