Place

Place objects represent physical locations which can be given a name and associated with a latitude and longitude somewhere on Earth. For example, the Caltrain station in San Francisco, CA at 700 4th St., which has a location of latitude 37.776905, longitude -122.395012, can be considered a Place. In order to provide accurate and thorough Place data, we use a database from factual.com. As such, all of our Places use the same UUIDs as those retrieved from factual.com.

{
  "factual_id": "19931850-dc2f-012e-561d-003048cad9da",
  "name": "Caltrain",
  "longitude": -122.395012,
  "latitude": 37.776905,
  "address": "700 4th St",
  "address_extended": "Ste 4",
  "locality": "San Francisco",
  "region": "CA",
  "postcode": "94107",
  "country_code": "us",
  "is_open": true,
  "website": "http://www.caltrain.com",
  "telephone": "(800) 660-4287",
  "categories": [
    {
      "id": "429",
      "labels": [
        "Transportation",
        "Transport Hubs",
        "Rail Stations"
      ]
    }
  ]
}

Place Fields

Field Type Description
factual_id string Primary identifier for a place. Uses factual.com's Place UUID.
name string Human-friendly name.
address string Street address.
address_extended string Apartment or Suite number in street address.
locality string City or town.
region string State, region, province etc.
admin_region string Additional sub-division (e.g. Wales).
post_town string Town used in postal addressing.
po_box string PO Box.
postcode string Postcode / zipcode.
country_code string A two-letter country code in ISO 3166-1 alpha-2 format.
latitude decimal Latitude in decimal degrees.
longitude decimal Longitude in decimal degrees.
is_open boolean Whether the establishment is still "in business" and/or open to the public and does not refer to business hours or whether it may be serving customers at any particular moment in time.
telephone string Telephone number in local formatting.
fax string Fax number in local formatting.
website string Official URL of the establishment.
categories list of objects
Field Type Description
labels list Human-friendly descriptive labels for this category. Ordered from general to specific.
id string Category ID. Corresponds to most specific category label.

In the future, Places may eventually sit at multiple categorical “leaf nodes” and as a result, we provide lists of category objects (though for now, no Place will be associated with more than one category ID).

Attaching Places to other resources

Places can be attached to any resource that allows annotations. You can insert Place data into any annotation using the +net.app.core.place replacement value and providing a factual_id. For more information, see the annotation replacement values documentation.

We provide a Checkin annotation as a core annotation for the common use case of using Place data to give users a way to say “I was here when I posted this”, though developers are free to use Place data in other contexts.

Retrieve a Place

Returns info about a Place object with a given factual_id.

Deduplication effects

Because it is possible for duplicate entries to exist for the same Place, Factual provides a method to deduplicate one Place object by “replacing” it with another. As a result, you may notice sometimes that when requesting a Place with one factual_id you will get back an entry with a different factual_id. When we return a different Place than the one you requested we are claiming, to the best of our knowledge, that it is equivalent to the one requested.

Endpoint

Method URL Token
GET https://api.app.net/places/{factual_id} Any

URL Parameters

Name Description
factual_id The Factual id of the Place to retrieve.

Example

to see more complete examples.

curl -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "X-ADN-Pretty-JSON: 1" \
    "https://api.app.net/places/19931850-dc2f-012e-561d-003048cad9da"
{
  "data": {
    "factual_id": "19931850-dc2f-012e-561d-003048cad9da",
    "name": "Caltrain",
    "longitude": -122.395012,
    "latitude": 37.776905,
    "address": "700 4th St",
    "address_extended": "Ste 4",
    "locality": "San Francisco",
    "region": "CA",
    "postcode": "94107",
    "country_code": "us",
    "is_open": true,
    "website": "http://www.caltrain.com",
    "telephone": "(800) 660-4287",
    "categories": [
      {
        "id": "429",
        "labels": [
          "Transportation",
          "Transport Hubs",
          "Rail Stations"
        ]
      }
    ]
  },
  "meta": {
    "code": 200
  }
}

Search for a Place

Performs a search for nearest places from given latitude and longitude. Optionally takes a q string to restrict matches on name (like autocomplete for Place names).

Returns a list of Places sorted by distance or distance/string match if q is provided. These are the same Place objects as returned by the previous endpoint but will also include a distance property which gives, in meters, the distance from the search centroid to the Place.

When using this endpoint, it is a requirement that all requests originate from user actions. As an example, acceptable use cases include when a user presses a button to search for local Places or when a user types a character to specify part of a Place name. Unacceptable use cases include automated access (e.g. "bots", "scrapers"), periodic scans and attempts to create comprehensive local caches or copies of the Place data.

We will be monitoring search usage and will take necessary actions to terminate unacceptable use.

Endpoint

Method URL Token
GET https://api.app.net/places/search User

Query String Parameters

Name Required? Type Description
latitude Required decimal Latitude of search location. Combined with longitude to create central point of search results.
longitude Required decimal Longitude of search location. Combined with latitude to create central point of search results.
q Optional string The name-based search query. Can be a partial string — for example, 'cre' will find any local 'creameries' and 'ice cream' locations.
radius Optional decimal Approximate radius (in meters) of bounding circle on results. For example, supplying radius=100 will limit all locations to be within 100 meters. Defaults to 100, ranges between 0.001 and 50,000.
count Optional integer Number of results to return. Defaults to 20, ranges between 1 and 100.
remove_closed Optional int (0 or 1) Set to 0 if you would like the result to include entities which are closed (is_closed=1) or 1 if you would only prefer to see results for entities that are open. Defaults to 1.
altitude Optional decimal Altitude of search location (in meters). Not presently used to generate search results but may be later.
horizontal_accuracy Optional decimal Accuracy of latitude/longitude parameters (in meters). Not presently used to generate search results but may be later.
vertical_accuracy Optional decimal Accuracy of altitude parameter (in meters). Not presently used to generate search results but may be later.

Example (no search string)

to see more complete examples.

curl -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "X-ADN-Pretty-JSON: 1" \
    "https://api.app.net/places/search?latitude=37.776905&longitude=-122.395012"
{
  "data": [
    {
      "factual_id": "19931850-dc2f-012e-561d-003048cad9da",
      "name": "Caltrain",
      "longitude": -122.395012,
      "latitude": 37.776905,
      "address": "700 4th St",
      "address_extended": "Ste 4",
      "locality": "San Francisco",
      "region": "CA",
      "postcode": "94107",
      "country_code": "us",
      "is_open": true,
      "website": "http://www.caltrain.com",
      "telephone": "(800) 660-4287",
      "categories": [
        {
          "id": "429",
          "labels": [
            "Transportation",
            "Transport Hubs",
            "Rail Stations"
          ]
        }
      ],
      "distance": 15.895655654
    }
  ],
  "meta": {
    "code": 200
  }
}

Example (search string, radius and count)

to see more complete examples.

curl -H "Authorization: Bearer <YOUR ACCESS TOKEN>" -H "X-ADN-Pretty-JSON: 1" \
    "https://api.app.net/places/search?latitude=37.776905&longitude=-122.395012&q=caltrain&count=1&radius=5000"
{
  "data": [
    {
      "factual_id": "19931850-dc2f-012e-561d-003048cad9da",
      "name": "Caltrain",
      "longitude": -122.395012,
      "latitude": 37.776905,
      "address": "700 4th St",
      "address_extended": "Ste 4",
      "locality": "San Francisco",
      "region": "CA",
      "postcode": "94107",
      "country_code": "us",
      "is_open": true,
      "website": "http://www.caltrain.com",
      "telephone": "(800) 660-4287",
      "categories": [
        {
          "id": "429",
          "labels": [
            "Transportation",
            "Transport Hubs",
            "Rail Stations"
          ]
        }
      ],
      "distance": 15.895655654
    }
  ],
  "meta": {
    "code": 200
  }
}