Looking for an easy way to integrate with the Hatebase API? Check out Andrew Welters' handy open source Hatebase PHP wrapper.

Hatebase is currently seeking a hosting partner. If you'd like to help out by donating your company's services, please let us know.

Meet the Hatebase API

Current API version:
3.0
Daily query limit:
100

The Hatebase API allows authorized users to retrieve Hatebase data asynchronously for use in their own applications. The API is a continual work in progress, so as new vesions of the API become available, old versions will be retired (after a suitable transition period). If you notice that your API calls have stopped returning data, please check the returned status messages to ensure your API URL hasn't become deprecated. Still having problems? Check our FAQs.

In general, sub-incremental versions are forwards-compatible (e.g. v1.2 will accept the same parameters as v1.1), but incremental versions will not (e.g. v2 will require different configuration than v1).

At this time, the Hatebase API is read-only.

Accessing the Hatebase API requires a private, unique, user-specific access key. You can obtain a key through your profile / account settings. Please keep this key secure (e.g. do not add it to browser-viewable code).

A query limit is enforced on the Hatebase API to ensure appropriate access by all users. For special applications, please let us know.


Summary of Changes

  • Addition of human-readable warnings, error codes and sighting types
  • Addition of offensiveness datapoint for vocabulary (will be empty until offensiveness meter is added to the website)
  • Addition of pagination to all queries. This limits any query to 1000 results, after which the results paginate, so to retrieve 1500 results, you would query the API twice: page 1 would provide the first 1000 results, and page 2 would provide the remainign 500 results.
  • Addition of unique ID for sightings

Input Parameters

The high-level schema for the Hatebase API is as follows:

http://api.hatebase.org/version/key/query-type/output/encoded-filters

URL Segment Format Options
version v{increment}-{sub-increment}
key {32-digit key}
query type {query type} vocabulary; sightings
output {output} xml; json
(encoded) filters {key}%3D{value}%7C{key}%3D{value} (see filter table below)

Filters are key/value pairs which correspond to output parameters. So for instance, to retrieve all sightings of English-language vocabulary pertaining to religion, the filter segment would properly read language%3Deng%7Cabout_religion%3D1.


Filter Applicable query Format Useful for
vocabulary vocabulary; sightings URL-encoded plaintext locating all sightings of a particular term
variant_of vocabulary; sightings URL-encoded plaintext determining all variants of a particular term
language vocabulary; sightings 3-character ISO 639-3 code
about_ethnicity vocabulary; sightings 1 (for true) or 0 (for false)
about_nationality vocabulary; sightings 1 (for true) or 0 (for false)
about_religion vocabulary; sightings 1 (for true) or 0 (for false)
about_gender vocabulary; sightings 1 (for true) or 0 (for false)
about_sexual_orientation vocabulary; sightings 1 (for true) or 0 (for false)
about_disability vocabulary; sightings 1 (for true) or 0 (for false)
about_class vocabulary; sightings 1 (for true) or 0 (for false)
archaic vocabulary; sightings 1 (for true) or 0 (for false)
page vocabulary; sightings any integer paginating through a large result
country sightings 2-character ISO 3166-2 code
city_or_community sightings URL-encoded plaintext
type sightings r (for recipient), o (for overheard), u (for used), t (for Twitter)
start_date sightings YYYY-mm-dd Defining the start of a date range
end_date sightings YYYY-mm-dd Defining the end of a date range

Some output parameters are not currently available as filters for obvious reasons, such as latitude and longitude (although in this case, a radial search may be made available in the future).


Output Parameters

For illustrative purposes, output has been displayed below as XML.

[hatebase]
  [version]VARCHAR(6)[/status]
  [status]TEXT[/status]
  [page]TINYINT(3)[/page]
  [number_of_results]INT[/number_of_results]
  [number_of_results_on_this_page]INT[/number_of_results_on_this_page]
  [warnings]
    [warning_code]INT(4)[/warning_code]
    [human_readable_warning]VARCHAR(255)[/human_readable_warning]
  [/warnings]
  [errors]
    [error_code]INT(4)[/error_code]
    [human_readable_error]VARCHAR(255)[/human_readable_error]
  [/errors]
  [number_of_queries_today]INT[/number_of_queries_today]
  [data]

    {data structure is dependent on requested query type}

  [/data]
[/hatebase]

Vocabulary data is presented with this structure:

    [datapoint]
        [vocabulary]VARCHAR(255)[/vocabulary]
        [variant_of]VARCHAR(255)[/variant_of]
        [pronunciation]VARCHAR(255)[/pronunciation]
        [meaning]TEXT[/meaning]
        [language]VARCHAR(3)[/language]
        [about_ethnicity]BINARY[/about_ethnicity]
        [about_nationality]BINARY[/about_nationality]
        [about_religion]BINARY[/about_religion]
        [about_gender]BINARY[/about_gender]
        [about_sexual_orientation]BINARY[/about_sexual_orientation]
        [about_disability]BINARY[/about_disability]
        [about_class]BINARY[/about_class]
        [archaic]BINARY[/archaic]
        [offensiveness]TINYINT(3)[/offensiveness]
        [number_of_revisions]INT[/number_of_revisions]
        [number_of_variants]INT[/number_of_variants]
        [variants]TEXT[/variants]
        [number_of_sightings]INT[/number_of_sightings]
        [last_sighting]DATETIME[/last_sighting]
        [number_of_citations]INT[/number_of_citations]
    [/datapoint]

Sightings data is presented with this structure:

    [datapoint]
        [sighting_id]INT(9)[/sighting_id]
        [date]DATE[/date]
        [country]VARCHAR(2)[/country]
        [city_or_community]VARCHAR(50)[/city_or_community]
        [lat]DECIMAL(11,7)[/lat]
        [long]DECIMAL(11,7)[/long]
        [type]CHAR(1)[/type]
        [human_readable_type]VARCHAR(15)[/human_readable_type]
        {plus related vocabulary data - see above}
    [/datapoint]

Error Handling

Incorrectly configured input parameters will result in an error being returned with the data. If the proper output format parameter cannot be determined, the default output for error messages is XML.

This API version has been deprecated and will soon be retired. Please upgrade to the latest API.

Summary of Changes

  • In the sightings query, recipient_or_overheard has been changed to type to accommodate a third potential value. So this field will now return "r" (recipient), "o" (overheard) or "u" (used).
  • A version field has been added.
  • Structured warning codes and error codes have been added.

Input Parameters

The high-level schema for the Hatebase API is as follows:

http://api.hatebase.org/version/key/query-type/output/encoded-filters

URL Segment Format Options
version v{increment}-{sub-increment}
key {32-digit key}
query type {query type} vocabulary; sightings
output {output} xml; json
(encoded) filters {key}%3D{value}%7C{key}%3D{value}

Filters are key/value pairs which correspond to output parameters. So for instance, to retrieve all sightings of English-language vocabulary pertaining to religion, the filter segment would properly read language%3Deng%7Cabout_religion%3D1.

The following additional filters are also available:

Query type Filter Format Useful for
Sightings start_date YYYY-mm-dd Defining the start of a date range
end_date YYYY-mm-dd Defining the end of a date range

Some output parameters are not currently available as filters for obvious reasons, such as latitude and longitude (although in this case, a radial search may be made available in the future).


Output Parameters

For illustrative purposes, output has been displayed below as XML.

<hatebase>
  <version>VARCHAR(6)</status>
  <status>TEXT</status>
  <warnings>
    <warning_code>INT(4)</warning_code>
  </warnings>
  <errors>
    <error_code>INT(4)</error_code>
  </errors>
  <number_of_queries_today>INT</number_of_queries_today>
  <data>

    {data structure is dependent on requested query type}

  </data>
</hatebase>

Vocabulary data is presented with this structure:

    <datapoint>
        <vocabulary>VARCHAR(255)</vocabulary>
        <variant_of>VARCHAR(255)</variant_of>
        <pronunciation>VARCHAR(255)</pronunciation>
        <meaning>TEXT</meaning>
        <language>VARCHAR(3)</language>
        <about_ethnicity>BINARY</about_ethnicity>
        <about_nationality>BINARY</about_nationality>
        <about_religion>BINARY</about_religion>
        <about_gender>BINARY</about_gender>
        <about_sexual_orientation>BINARY</about_sexual_orientation>
        <about_disability>BINARY</about_disability>
        <about_class>BINARY</about_class>
        <archaic>BINARY</archaic>
        <number_of_revisions>INT</number_of_revisions>
        <number_of_variants>INT</number_of_variants>
        <variants>TEXT</variants>
        <number_of_sightings>INT</number_of_sightings>
        <last_sighting>DATETIME</last_sighting>
        <number_of_citations>INT</number_of_citations>
    </datapoint>

Sightings data is presented with this structure:

    <datapoint>
        <date>DATE</date>
        <country>VARCHAR(2)</country>
        <city_or_community>VARCHAR(50)</city_or_community>
        <lat>DECIMAL(11,7)</lat>
        <long>DECIMAL(11,7)</long>
        <type>CHAR(1)</type>
        {plus related vocabulary data - see above}
    </datapoint>

Error Handling

Incorrectly configured input parameters will result in an error being returned with the data. If the proper output format parameter cannot be determined, the default output for error messages is XML.

This API version is now retired. Please upgrade to the latest API.

Warning codes

1 Approaching maximum daily queries.
2 No vocabulary was retrieved based on your input parameters.
3 No sightings were retrieved based on your input parameters.
4 This API version has been deprecated and will soon be retired. Please upgrade to the latest API.

Error codes

1 No valid filters found.
2 Missing API key.
3 Invalid API key.
4 Maximum daily queries already reached; the query limit resets every 24 hours.
5 Unable to determine a valid query type.
6 This API version is now retired. Please upgrade to the latest API.