App Guidelines

From GCD
Revision as of 21:46, 2 January 2022 by Adia (talk | contribs) (General updates; correct CC license link)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

So, you are developing an application re-using the GCD data? Great! We want our work to be useful for as many people and as widely as possible. To ensure a good experience for users of your app as well as a productive co-operation with the GCD Project, the following guidelines might be of interest. Please note that this applies equally to web apps, desktop or mobile apps, or even republishing our data in print.

Make sure users know the origin of the data

First of all, you've read our Data Distribution page, right? In particular, the Creative Commons Attribution-ShareAlike license, under which the data is available, requires that information coming from us is credited to the Grand Comics Database™, and a link back to the appropriate page in our site is provided if possible.

Making the relationship between the data you are using and the GCD project clear to your users is not only a legal requirement, but it's also mutually beneficial. This way, errors or omissions in our data can be pointed out to us, so that our completeness and accuracy improves as more people work with the GCD, and in turn you get both better data in the future as well as more satisfied users who know how they can fix problems with the source information.

It would be helpful to make sure that users are at least briefly made aware of the best best way to contribute back to the GCD when you point them our way. Becoming indexers and making fixes or additions directly through our Online Indexing (OI) interface is best and ensures that their contributions are incorporated to the GCD data in the most direct and efficient way. In comparison, submitting an error report or contacting us via email means that the report has to be handled by other overworked indexers or editors and will naturally take longer.

Please also make sure that the way GCD information is used in your app doesn't confuse users. Our original aim is documentation and research and our data isn't necessarily organized and presented in the optimum way for those using it, for instance, to track their collections, create an on-line comic shop, create statistics, or any of various other areas of interest. Some possible gotchas:

  • For series, the name as appears in the indicia takes precedence and in general series are split when their title changes. This might mean that users might not find all the books they're looking for in the same series or under the title they first try to search for
  • The GCD advanced search interface is somewhat inflexible and, for example, punctuation marks might cause a search to fail. We recommend starting from our "Everything" full-text search and drilling down to the desired data by applying relevant filters. We encourage you to create a better search system inside your app if appropriate.
  • Publishers are a complicated topic and our model, while comprehensive, might not match exactly what you have in mind - please see the User's Guide to Publishers

We don't offer access to our data via an API, only as a database dump download. If appropriate for your use-case, you could create your own back-end data store and API and periodically update it by importing our DB dumps. Please note that as the GCD is currently in a process of migrating story credits and character appearances from text-based fields to database objects with foreign key links, you should be prepared to handle both, even for the same issue or story.

To keep abreast of changes to the DB schema, please track our code repository or the gcd-tech mailing list.


The Grand Comics Database (GCD) uses copyrighted cover images following the "fair use" doctrine. Comic cover images are stored and provided in context of information about (and to help GCD users identify) comic publications.

  • The GCD will not distribute cover images in bulk.
  • The GCD will not facilitate or encourage any activity that infringes on the copyrights of any publication.
  • The GCD will not tolerate the use of aggressive site scraping (including image harvesting) that impacts performance of the site.

Case Study: Comic Book Inventory (CBI)
CBI came up with a solution that provides their mobile app users with GCD cover images without scraping the whole GCD site or relying on bulk image distribution. When a CBI user looks up a specific comic, the CBI app checks to see if the cover image is available locally, first on the user's device, and then on the app's back-end servers. If the image is not found there, the CBI app server will download the requested image from the GCD web site. CBI is simply archiving the downloads preventing the app from downloading the same covers repeatedly.