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

Some, but not all, of the API endpoints require an API key. Get an API key here.

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

This API is designed to provide you with raw access to the latest neighborhood news on EveryBlock, across all of the current EveryBlock metros. But because EveryBlock deals with a diversity of news -- 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 only 16 U.S. metros, although we've been growing to more and more.
  • Each metro has different news availability. Certain types of news are available across all metros (e.g., locations in the media and user discussions); other types of news 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 news available, the nature of the data may differ. For example, our data for crime in Chicago is wildly different than crime in New York City: Chicago crime data is updated daily, with a separate record for each crime report, with addresses to the block level. New York crime data is updated weekly, but no individual crimes are mentioned in the data, only precinct-wide reports that will tell you, for example, that Precinct 1 had five robberies between Sept. 6 and Sept. 12, 2010.

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 news and (obviously) new news items.

EveryBlock serves 16 metros. In all but one case (Miami-Dade), 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 == "announcements" while this news item has schema == "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 or community boards. These are known as location types. A specific item in a location type is called a location. For example, Albany Park is a location with location_type == neighborhood.

We currently provide three API endpoints: metros(), schemas() and newsitems(). Each is described in a section below.

This is a simple REST-style Web API. Make GET requests via HTTP, and we'll return an XML document with the content you requested.

Each XML result is wrapped in a top-level <result> tag, which contains a <status> section like so:

<result>
    <status>
        <code>0</code>
        <message>Success</code>
    </status>
    <-- Actual result content goes here... -->
</result>

Your app should check the status code. If it's 0, then all is well. If it's -1, then something went wrong -- either you didn't provide valid API parameters or the API is temporarily unavailable.

http://api.everyblock.com/0.1/metros/

Returns a list of all current EveryBlock metros, with some useful data about each.

No API key is required.

Each <metro> element has the following XML attributes:

  • name -- The human-readable name of the metro.
  • short_name -- The all-lowercase code for the metro, used in EveryBlock subdomains (e.g., chicago.everyblock.com). You'll need this in the schemas() and newsitems() endpoints.
  • city -- The human-readable name of the major city in the metro. This is useful for metros where EveryBlock covers more than just the city limits; in that case, the name is the name of the metro (Miami-Dade) while the city is just the city (Miami).
  • state -- The two-letter state abbreviation.
  • tz -- The time zone.
  • sw_longitude, sw_latitude, ne_longitude, ne_latitude -- The coordinates representing the bounding box of the metro area. Note that this is just a bounding box, which means there's no guarantee that each point within the box is covered by EveryBlock. Not every point within the box is covered by EveryBlock, but all of EveryBlock's coverage fits within the box.

http://api.everyblock.com/0.1/schemas/?metro=[METRO]

Returns a list of all schemas in the requested metro.

GET parameters:

  • metro (required) -- the short_name from metros().

No API key is required.

Each <schema> element has the following XML 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".
  • url -- The full URL of the schema's index page on everyblock.com.
  • url_about -- The full URL of the schema's "about" page on everyblock.com.

Each schema also has a list of one or more fields. (These are "attributes" from the Terminology section above.) Each <field> element has the following XML attributes:

  • name -- The all-lowercase name, with underscores instead of spaces.
  • pretty_name -- The human-readable name of the field.
  • pretty_name_plural -- The human readable plural name of the field.

http://api.everyblock.com/0.1/location_types/?metro=[METRO]

Returns a list of all location types in the requested metro.

GET parameters:

  • metro (required) -- the short_name from metros().

No API key is required.

Each <location_type> element has the following XML attributes:

  • id -- A numeric ID. This is unique within the metro.
  • name -- The name of the location type, 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 location type, likewise in all lowercase.
  • slug -- The code for the location type, containing no spaces, which is used in URLs and in other places where we need to represent a location type without spaces.
  • url -- The full URL of the location type's index page on everyblock.com.

In case you're curious, blocks are not a location type; they're represented as a separate concept in our system and aren't available via this API at this point.

http://api.everyblock.com/0.1/locations/?metro=[METRO]&location_type=[LOCATION_TYPE]

Returns a list of all locations with the requested location type in the requested metro. (For example, a list of all the ZIP codes or neighborhoods.)

GET parameters:

  • metro (required) -- the short_name from metros().
  • location_type (required) -- the slug from location_types().

No API key is required.

Each <location> element has the following XML 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 news page on everyblock.com.

http://api.everyblock.com/0.1/newsitems/?metro=[METRO]&api_key=[API_KEY]&since=[START_DATE]&schemas=[SCHEMAS]

Returns a list of all news items in the requested metro, since the given time.

GET parameters:

  • metro (required) -- the short_name from metros().
  • api_key (required) -- your EveryBlock API key.
  • since (optional) -- the date/time at which to start, in YYYY-MM-DD-HHMM format (e.g., for 7 p.m. on January 6, 2010, use 2010-01-06-1900). If you omit this parameter or enter a date/time more than 24 hours ago, this will default to 24 hours ago. There's currently no way of retrieving news more than 24 hours old.
  • schemas (optional) -- the schemas to limit this to. Use a comma-separated list of schema IDs. For example, schemas=1,4,6 will tell the API only to include news items of schema IDs 1, 4 or 6.

Each <newsitem> element has the following XML attributes:

  • id -- A numeric ID. This is unique within the metro.
  • title -- The newsitem'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.
  • 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.
  • location_name -- The name of the location that this item pertains to, e.g., "123 Main St." or "Wicker Park".
  • schema -- The slug of the news item's schema.
  • schema_id -- The id of the news item's schema.
  • pub_date -- The date/time this item was added to EveryBlock, in the metro's local time zone.
  • longitude and latitude -- The longitude/latitude of the news item's location. Most news items on EveryBlock are natively represented as points, but if the news item applies "evenly" to a neighborhood (e.g., if the location_name is something like "Downtown"), then these values will be the centroid of the neighborhood.

Each <newsitem> element also has an <attributes> subelement, containing one or more <attribute> elements. These are "attributes" as defined in Terminology and are different for each schema. The name corresponds to the <field> name from the schemas() endpoint.

Some more notes about this endpoint:

  • Suggested usage here is to hit the API once per city a couple of times a day, keeping track of the last time you hit it and passing that time as since. Please do not hit this frequently (i.e., every minute), as it's intensive on our servers.
  • For the most part, news items never change, but in some cases, for some schemas, we update their data. (For example, a police department may reclassify an assault to an aggravated assault.) You should consider this API a "snapshot" of EveryBlock data at that given moment; we have no way for alerting you to changes in the data.
  • For details on the nature and quirks of a schema, check out the schema's "about" page. You can get that URL from the schemas() endpoint or by clicking around the everyblock.com site.
  • Most of the data from our live site is included in this API. We may make changes to data availability over time.

Join the free EveryBlock API Google Group to ask questions, help other API users out and share what you've created.

If you have any questions you'd like to ask privately, feel free to email us at feedback@everyblock.com.