craigslist Reference Web Services

last modified: 07/07/2014

Overview
Areas API
Categories API

Overview

craigslist Reference Web Services APIs offer a way to provide commonly used craigslist classification data to our users.

Our web services use HTTP requests to specific URLs, and return JSON encoded data.

Areas API

Areas Request

Areas API requests should be in the format:

http://reference.craigslist.org/Areas/AreaID

To get the entire list of Areas, omit "/AreaID" from your request.

AreaID (optional) - the unique ID identifying a particular Area, use this to request data for a particular Area.

Areas Response

If AreaID is supplied, but the value provided is not valid, you will receive an HTTP response status of '404 Not Found'.

For the request:

http://reference.craigslist.org/Areas

The JSON returned is:

[
   {
      "Abbreviation" : "sfo",
      "AreaID" : "1",
      "Country" : "US",
      "Description" : "SF bay area",
      "Hostname" : "sfbay",
      "Latitude" : "37.500000",
      "Longitude" : "-122.250000",
      "Region" : "CA",
      "ShortDescription" : "SF bay area",
      "SubAreas" : [
         {
            "Abbreviation" : "sfc",
            "Description" : "city of san francisco",
            "ShortDescription" : "san francisco",
            "SubAreaID" : "1"
         },
         {
            "Abbreviation" : "sby",
            "Description" : "south bay area",
            "ShortDescription" : "south bay",
            "SubAreaID" : "2"
         },
         {
            "Abbreviation" : "eby",
            "Description" : "east bay area",
            "ShortDescription" : "east bay",
            "SubAreaID" : "3"
         },
         {
            "Abbreviation" : "pen",
            "Description" : "peninsula",
            "ShortDescription" : "peninsula",
            "SubAreaID" : "4"
         },
         {
            "Abbreviation" : "nby",
            "Description" : "north bay / marin",
            "ShortDescription" : "north bay",
            "SubAreaID" : "5"
         },
         {
            "Abbreviation" : "scz",
            "Description" : "santa cruz co",
            "ShortDescription" : "santa cruz",
            "SubAreaID" : "6"
         }
      ],
      "Timezone" : "America/Los_Angeles"
   },

   ... (other Areas)

]

For the request:

http://reference.craigslist.org/Areas/1

The JSON returned is:

{
   "Abbreviation" : "sfo",
   "AreaID" : "1",
   "Country" : "US",
   "Description" : "SF bay area",
   "Hostname" : "sfbay",
   "Latitude" : "37.500000",
   "Longitude" : "-122.250000",
   "Region" : "CA",
   "ShortDescription" : "SF bay area",
   "SubAreas" : [
      {
         "Abbreviation" : "sfc",
         "Description" : "city of san francisco",
         "ShortDescription" : "san francisco",
         "SubAreaID" : "1"
      },
      {
         "Abbreviation" : "sby",
         "Description" : "south bay area",
         "ShortDescription" : "south bay",
         "SubAreaID" : "2"
      },
      {
         "Abbreviation" : "eby",
         "Description" : "east bay area",
         "ShortDescription" : "east bay",
         "SubAreaID" : "3"
      },
      {
         "Abbreviation" : "pen",
         "Description" : "peninsula",
         "ShortDescription" : "peninsula",
         "SubAreaID" : "4"
      },
      {
         "Abbreviation" : "nby",
         "Description" : "north bay / marin",
         "ShortDescription" : "north bay",
         "SubAreaID" : "5"
      },
      {
         "Abbreviation" : "scz",
         "Description" : "santa cruz co",
         "ShortDescription" : "santa cruz",
         "SubAreaID" : "6"
      }
   ],
   "Timezone" : "America/Los_Angeles"
}

Area JSON Object Definitions

Areas
Name	Example	Definition
Abbreviation	sfo	A unique, three-letter craigslist-defined Area Abbreviation (note: while there may be some overlap, Area Abbreviations are not the same as IATA airport codes)
AreaID	1	An integer, a craigslist-defined unique Area identifier
Country	US	Area's ISO 3166-1 alpha-2 two-letter country code
Description	SF bay area	craigslist-defined text description of Area
Hostname	sfbay	craigslist hostname for Area (e.g. http://sfbay.craigslist.org/)
Latitude	37.500000	Latitude of approximate Area center
Longitude	-122.250000	Longitude of approximate Area center
Region	CA	State, Province, etc.
ShortDescription	SF bay area	Shorter version of Area Description (may be the same as Description)
SubAreas	see table below	List of SubAreas for this Area (key will not exist if an Area has no SubAreas)
Timezone	America/Los_Angeles	Area's time zone formatted according to the IANA Time Zone Database (aka tz database / tzdata / zoneinfo database / Olsen database)

SubArea Definitions

SubAreas
Name	Example	Definition
Abbreviation	sfc	Three-letter craigslist-defined SubArea Abbreviation, unique to the Area
Description	city of san francisco	craigslist-defined text description of SubArea
ShortDescription	san francisco	Shorter version of SubArea Description (may be the same as Description)
SubAreaID	1	An integer, a craigslist-defined SubArea identifier, unique to the Area

Categories API

Categories Request

Categories API requests should be in the format:

http://reference.craigslist.org/Categories/CategoryID

To get the entire list of Categories, omit "/CategoryID" from your request.

CategoryID (optional) - the unique ID identifying a particular Category, use this to request data for a particular Category.

Categories Response

If CategoryID is supplied, but the value provided is not valid, you will receive an HTTP response status of '404 Not Found'.

For the request:

http://reference.craigslist.org/Categories

The JSON returned is:

[
   {
      "Abbreviation" : "apa",
      "CategoryID" : "1",
      "Description" : "apts/housing for rent",
      "Type" : "H"
   },

   ... (other Categories)

]

For the request:

http://reference.craigslist.org/Categories/1

The JSON returned is:

{
   "Abbreviation" : "apa",
   "CategoryID" : "1",
   "Description" : "apts/housing for rent",
   "Type" : "H"
}

Category JSON Object Definitions

Categories
Name	Example	Definition
Abbreviation	apa	A unique, three-letter/digit craigslist-defined Category Abbreviation
CategoryID	1	An integer, a craigslist-defined unique Category identifier
Description	apts/housing for rent	craigslist-defined text description of Category
Type	see table below	Category Type

Category Type Definitions

Type	Description
B	Services
C	Community
E	Events
G	Gigs
H	Housing
J	Jobs
P	Personals
R	Resumes
S	For Sale / Wanted