Skip to content

Latest commit

 

History

History
347 lines (307 loc) · 12.3 KB

index.md

File metadata and controls

347 lines (307 loc) · 12.3 KB
Raw
title
Place

Place

  • TOC {:toc}

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 "GET", "places/[factual_id]", "Any" %>

<%= url_params [ ["factual_id", "The Factual id of the Place to retrieve."] ]%>

Example

GET https://alpha-api.app.net/stream/0/places/19931850-dc2f-012e-561d-003048cad9da

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

{::options parse_block_html="true" /}

**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 "GET", "places/search", "User" %>

<%= query_params_typed 'Query String Parameters', [

["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 <code>radius=100</code> 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). <em>Not presently used to generate search results but may be later.</em>"],

["horizontal_accuracy", :optional, "decimal", "Accuracy of <code>latitude</code>/<code>longitude</code> parameters (in meters). <em>Not presently used to generate search results but may be later.</em>"],

["vertical_accuracy", :optional, "decimal", "Accuracy of <code>altitude</code> parameter (in meters). <em>Not presently used to generate search results but may be later.</em>"]

]%>

Example (no search string)

GET https://alpha-api.app.net/stream/0/places/search?latitude=37.761334&longitude=-122.426276

{
    "data": [
        {
            "distance": 17.9039689207,
            "name": "Dolores Park Tennis Courts",
            "locality": "San Francisco",
            "region": "CA",
            "longitude": -122.426165,
            "is_open": true,
            "factual_id": "4c469fdf-8f28-43c7-a9f6-c1cb5e95ff9f",
            "latitude": 37.761469,
            "country_code": "us",
            "categories": [
                {
                    "labels": [
                        "Sports and Recreation",
                        "Racquet Sports",
                        "Tennis"
                    ],
                    "id": "399"
                }
            ]
        },
        {
            "distance": 17.9039689207,
            "name": "Dolores Park",
            "locality": "San Francisco",
            "region": "CA",
            "telephone": "(415) 831-5520",
            "longitude": -122.426165,
            "is_open": true,
            "factual_id": "b7a7f1c8-c68f-4f24-92cb-668cf05658e2",
            "latitude": 37.761469,
            "country_code": "us",
            "categories": [
                {
                    "labels": [
                        "Landmarks",
                        "Parks"
                    ],
                    "id": "118"
                }
            ]
        },
        ...
    ],
    "meta": {
        "code": 200
    }
}

Example (search string, radius and count)

GET https://alpha-api.app.net/stream/0/places/search?latitude=37.78592&longitude=-122.400751&q=bi-rite&count=1&radius=5000

{
    "data": [
        {
            "website": "http://www.biritecreamery.com",
            "distance": 2771.26823449,
            "name": "Bi-Rite Creamery",
            "locality": "San Francisco",
            "region": "CA",
            "telephone": "(415) 626-5600",
            "longitude": -122.409012,
            "is_open": true,
            "postcode": "94110",
            "factual_id": "96304850-ea37-012e-3020-00259004449e",
            "address": "3692 18th St",
            "latitude": 37.761868,
            "country_code": "us",
            "categories": [
                {
                    "labels": [
                        "Social",
                        "Food and Dining",
                        "Restaurants"
                    ],
                    "id": "347"
                }
            ]
        }
    ],
    "meta": {
        "code": 200
    }
}