You can use the EveryBlock Content API to publish recent EveryBlock content in your own site or application.

If you're not familiar with EveryBlock, read our about page and FAQ. The main takeaway is that EveryBlock gathers, organizes and publishes content at the level of neighborhood and city block. Given a location, we can tell you what's been happening there recently.

This API is designed to provide you with access to the latest content on EveryBlock, across all of the current EveryBlock metros. But because EveryBlock deals with a diversity of sources -- we index everything from blog posts to crime reports, and information varies by city -- you'll need to understand some important things before you dive into the API:

  • EveryBlock covers 9 metros: Boston, Chicago, Denver, Fresno, Hialeah, Houston, Medford, Nashville and Philadelphia.
  • Each metro has different content availability. Certain types of content are available across all metros (e.g., locations in the media and user discussions); other types of content are available in a subset of our metros; still other types of news are available only in a single metro.
  • Even when multiple metros have the same content available, the nature of the data may differ.

We've designed our API to help you through these quirks by (we hope) giving you a standard, abstract and consistent way of accessing our data. Our goal is to make things future-proof so that your application will magically continue working when we add cities, new types of content and (obviously) new content itself.

EveryBlock serves 9 metros. It's technically not the entire metro area -- just the city proper -- but we call these metros for future-compatibility.

Each piece of news on EveryBlock -- whether it's a link to a mainstream news article, a user discussion, etc. -- is called a news item. Simply put, a news item is a piece of data that has a date and a location. One way to think of EveryBlock is as a geographic filter of these news items: enter an address, and we'll show you news items near that address.

A schema is a news item's type. For example, this news item has schema of "announcements" while this news item has schema of "crime".

All news items have certain things in common -- each has an ID, a title, a URL, a location (both human-readable and longitude/latitude), a schema and a publication date. Beyond that, a news item may have schema-specific attributes, which are key-value pairs of structured data; for example, a crime may have a case number, a crime type and a police beat number, while a user-posted announcement may have a user ID and text of the announcement.

Each metro area that EveryBlock serves has a different list of available schemas.

EveryBlock offers distinct pages for neighborhoods, ZIP codes and, in some cases, city-specific entities such as wards. These are known as location types. A specific item in a location type is called a location. For example, Albany Park is a location of the neighborhood type.

We currently provide various API endpoints for accessing accessing and filtering the aformentioned news items. Each is described in a section below.

This is a REST-style Web API. Make GET requests via HTTP, and we'll return a document with the content you requested. The document format can specified in the request. The supported formats are JSON, JSONP, and XML. If no format is specified, endpoints default to JSON.

Format types can be specified via an Accept header or extension within the URL.

      Headers:
            JSON: Accept: application/json
            JSONP: Accept: application/javascript
            XML: Accept: application/xml

        Extensions:
            JSON: .json
            JSONP: .jsonp
            XML: .xml
    

An example using extensions: https://api.everyblock.com/content/.json

All endpoints are hosted on https://api.everyblock.com and require authentication. Authentication is handled with an API token in the HTTP request headers. Get an API token here.

Here is an example:

Here is an example:

      GET /content/ HTTP/1.1
      Host: api.everyblock.com
      Authorization: Token 90fe24d329973b71272faf3f5d17a8602bff996b
    

Here is an example using the token URL parameter:

        https://api.everyblock.com/content/chicago/?token=90fe24d329973b71272faf3f5d17a8602bff996b
    

Returns a list of all current EveryBlock metros, with some useful data and related data links within the API.

/content/

The content endpoint is merely a list of all current EveryBlock metros. See the Metro Endpoint for output details.

Returns a specific EveryBlock metro, with some useful data and related data links within the API.

/content/[metro]/

URL parameters:

Each metro element contains the following attributes:

  • short_name -- A unique identifier for a metro.
  • metro_name -- The nice name for a metro.
  • schemas -- The API URL to schemas for the metro. See the Schema Endpoint.
  • topnews -- The API URL to popular content for the metro. See the Popular News Item Endpoint
  • neighborhoods -- The API URL to neighborhoods for the metro. See the Location Endpoint.
  • wards --The API URL to wards for the metro. See the Location Endpoint.
  • zipcodes -- The API URL to zipcodes for the metro. See the Location Endpoint.
  • custom_locations -- The API URL to custom locations for the metro. See the Location Endpoint..

Returns the schemas for a specific metro.

/content/[metro]/schemas/

URL parameters:

Each schema element contains the following attributes:

  • id -- A numeric ID. This is unique within the metro.
  • name -- The name of the schema, in all lowercase. It's in lowercase so that applications have the option of capitalizing the first word automatically if it's at the start of a sentence, or leaving it as-is for usage in the middle of a sentence.
  • plural_name -- The plural name of the schema, likewise in all lowercase.
  • slug -- The code for the schema, containing no spaces, which is used in URLs and in other places where we need to represent a schema without spaces.
  • indefinite_article -- Either a or an, depending on the rules of English grammar. For "crime," it would be "a". For "anchovy" it would be "an".
  • is_active -- The current status of the schema. If true, the schema is currently being using for new content. If false, the schema is not being used for new content.
  • about -- The full URL of the schema's "about" page on everyblock.com.

Returns the popular news items for a specific metro. It is the API equivalent to Popular in Chicago. It is limited to 5 days worth of content.

      /content/[metro]/topnews/
    

URL parameters:

Query string parameters:

  • schema -- A schema's slug. This can be found via the Schema Endpoint. It is used to filter results to one or more schemas. To filter multiple schema specify the query string parameter multiple times. For example, the following query string would be used to access only crime and neighbor messages.
    ?schema=crime&schema=announcements
  • date -- Sorts returned news items by date.News item results are by default sorted by their Everyblock blockscore in descending order. Newsitems may also be returned sorted by date; specifying the the 'date' url parameter and it's value as either 'ascending' or 'descending'. For example, the following query string will return news items sorted by date ascending.
    ?date=ascending
  • source_id -- Filter returned news items by source number.News item results are identified by a 'source' attribute number which indicates their origin. Newsitems may be returned filtered by source number; specifying the the "source_id" url parameter and the desired source number as value. For example, the following query string will return only news items with source attribute id's of 4 and 245.
    ?source_id=4&source_id=245
  • source_name -- Filter returned news items by source name.News item results are identified by a source name which indicates their origin. Newsitems may be returned filtered by source name; specifying the the "source_name" url parameter and the desired source name as value. For example, the following query string will return only news items with a source name of "everyblock.com" and "NBC Universal". Source names that contain spaces are passed either with '+' or '%20' to replace the spaces. Example.
    ?source_name=everyblock.com&source_name=NBC%20Universal
  • attribute -- Filter the returned news item's associated attributes.News item results are displayed with associated attributes and values; specifying the the 'attribute' url parameter and the desired attribute as value, multiple attributes may be chained with the "&" operator. For example, the following query string will return news items with only the "comment" and "source" attributes displayed.
    ?attribute=comment&attribute=source

Results are paginated, so they come in an envelope containing the following attributes:

  • count -- A count of the total number of news items available from this endpoint.
  • next -- An API link to the next page of news items. It will be null if a next page does not exist.
  • previous -- An API link to the previous page of news items. It will be null if a previous page does not exist.
  • results -- A list of news items on the current page.

Each news item element has the following attributes:

  • id -- A numeric ID. This is unique within the metro.
  • title -- The news item's title. For news articles, it's the headline; for public records like crimes, it's a headline we've put automatically constructed from the structured data.
  • pub_date -- The date/time this item was published on EveryBlock, in the metro's local time zone.
  • item_date -- The date of the item. This can be before, on, or after the pub_date. For example, a food inspection might be published on the site on November 3rd, but the inspection actually occured on October 20th. In this case the pub_date would be October 20th and the item_date would be November 3rd.
  • location_name -- The name of the location that this item pertains to, e.g., "123 Main St." or "Wicker Park".
  • url -- The full URL of the item on everyblock.com. Note that in some cases (for news articles, school reviews, etc.) this might redirect to a third-party site.
  • reaction_count -- The number of reactions the news item received from EveryBlock members.
  • reaction_score -- The average reaction score the news item received from EveryBlock members.(Range is between Great 3 to Terrible -2)
  • comment_count -- The number of comments the news item received from EveryBlock members.
  • embed -- This displays information about the newsitem's embedded content if there is any else it displays "null". The fieldnames provided here change based on the embeded media attached to this newsitem.
    provider_url: This is the base url the embeded content originates from.
            description: An excerpt from the url from the first large body of text on the url page.
            title: The value of the embeded media page's title tag.
            url: The url to view the embeded media.
            thumbnail_width: Width of the embeded media's thumbnail if applicable in pixels.
            thumbanail_url: Url to the thumbanil image used if applicable.
            provider_name: The name of the emeded media provider.
            thumbail_height: Height of the embeded media's thumbnail if applicable in pixels.
            type: The category of embed this media falls into. (link, image, video etc.) 

Returns the locations for the specified type, with some useful data and related links within the API.

      /content/[metro]/[location_type]/
      /content/[metro]/neighborhoods/
      /content/[metro]/wards/
      /content/[metro]/zipcodes/
      /content/[metro]/custom-locations/
    

URL parameters:

  • metro -- A metro's short_name. This can be found via the Content Endpoint.
  • location_type -- A location type. This can be neighbhoods, wards, zipcodes or custom-locations.

Each location element has the following attributes:

  • id -- A numeric ID. This is unique within the metro.
  • name -- The name of the location, in correct capitalization.
  • slug -- The code for the location, containing no spaces, which is used in URLs and in other places where we need to represent a location without spaces.
  • url -- The full URL of the location's page on everyblock.com.
  • timeline -- The API URL for the news item timeline.

Returns the locations for the specified type, with some useful data and related links within the API. It is limited to 5 days worth of content.

      /content/[metro]/locations/[location]/timeline/
    

URL parameters:

Query string parameters:

  • schema -- A schema's slug. This can be found via the Schema Endpoint. It is used to filter results to one or more schemas. To filter multiple schema specify the query string parameter multiple times. For example, the following query string would be used to access only crime and neighbor messages.
    ?schema=crime&schema=announcements
  • date -- Sorts returned news items by date.News item results are by default sorted by their Everyblock blockscore in descending order. Newsitems may also be returned sorted by date; specifying the the 'date' url parameter and it's value as either 'ascending' or 'descending'. For example, the following query string will return news items sorted by date ascending.
    ?date=ascending
  • attribute -- Filter the returned news item's associated attributes.News item results are displayed with associated attributes and values; specifying the the 'attribute' url parameter and the desired attribute as value, multiple attributes may be chained with the "&" operator. For example, the following query string will return news items with only the "comment" and "source" attributes displayed.
    ?attribute=comment&attribute=source
  • source_id -- Filter returned news items by source number.News item results are identified by a 'source' attribute number which indicates their origin. Newsitems may be returned filtered by source number; specifying the the "source_id" url parameter and the desired source number as value. For example, the following query string will return only news items with source attribute id's of 4 and 245.
    ?source_id=4&source_id=245
  • source_name -- Filter returned news items by source name.News item results are identified by a source name which indicates their origin. Newsitems may be returned filtered by source name; specifying the the "source_name" url parameter and the desired source name as value. For example, the following query string will return only news items with a source name of "everyblock.com" and "NBC Universal". Source names that contain spaces are passed either with '+' or '%20' to replace the spaces. Example.
    ?source_name=everyblock.com&source_name=NBC%20Universal

Results are paginated, so they come in an envelope containing the following attributes:

  • count -- A count of the total number of news items available from this endpoint.
  • next -- An API link to the next page of news items. It will be null if a next page does not exist.
  • previous -- An API link to the previous page of news items. It will be null if a previous page does not exist.
  • results -- A list of news items on the current page.

Each news item element has the following attributes:

  • id -- A numeric ID. This is unique within the metro.
  • title -- The news item's title. For news articles, it's the headline; for public records like crimes, it's a headline we've put automatically constructed from the structured data.
  • pub_date -- The date/time this item was added to EveryBlock, in the metro's local time zone.
  • item_date -- The date of the item. This can be before, on, or after the pub_date. For example, a food inspection might be published on the site on November 3rd, but the inspection actually occured on October 20th. In this case the pub_date would be October 20th and the item_date would be November 3rd.
  • location_name -- The name of the location that this item pertains to, e.g., "123 Main St." or "Wicker Park".
  • url -- The full URL of the item on everyblock.com. Note that in some cases (for news articles, school reviews, etc.) this might redirect to a third-party site.
  • reaction_count -- The number of reactions the news item received from EveryBlock members.
  • reaction_score -- The average reaction score the news item received from EveryBlock members.(Range is between Great 3 to Terrible -2)
  • comment_count -- The number of comments the news item received from EveryBlock members.
  • source -- A numeric Source ID. This can further be used to query News Items specific to the source via the source_id query parameter.
  • source_name -- Name of the source for the News Item. Source Name can be used for display purposes.

If you have any questions you'd like to ask, feel free to contact us via the Feedback form.