Places endpoint

Location search API

Finds places by name (q), or the places around a point (lat and lng).

GEThttps://storiesfly.com/api/v1/location/search

Price 1 request
Answers up to 24 hours old

Parameters

All parameters go in the query string.

Name	Type	Sent	Description
`q`	string	optional	Place name to look for, 1 to 100 characters. Send this, or lat and lng.
`lat`	string	optional	Latitude, from -90 to 90. Send with lng, instead of q.
`lng`	string	optional	Longitude, from -180 to 180. Send with lat, instead of q.

Example request

Put your own key in the header.

curl "https://storiesfly.com/api/v1/location/search?q=coffee" \
  -H "X-Api-Key: sf_live_your_key"

const res = await fetch(
  "https://storiesfly.com/api/v1/location/search?q=coffee",
  { headers: { "X-Api-Key": process.env.STORIESFLY_KEY } }
);
const data = await res.json();

import os
import requests

r = requests.get(
    "https://storiesfly.com/api/v1/location/search",
    params={"q": "coffee"},
    headers={"X-Api-Key": os.environ["STORIESFLY_KEY"]},
)
data = r.json()

Example response

200 OK · X-Units-Charged: 1

{
  "locations": [
    {
      "id": "106256377723342",
      "name": "Coffee Time",
      "address": null,
      "city": null,
      "lat": 40.75267612,
      "lng": -73.97777108
    },
    {
      "id": "242744966653060",
      "name": "Ralph's Coffee",
      "address": null,
      "city": null,
      "lat": null,
      "lng": null
    }
  ],
  "next_cursor": null,
  "has_more": false
}

A real answer, shortened: lists are cut to two items and long texts to 160 characters.

Price and freshness

A call takes 1 request. Free requests are spent first, then your balance. The pricing page has the rates.

Answers are kept for up to 24 hours. Asking again inside that time returns the same answer and takes 1 request again.

Errors

A failed call answers with an HTTP status and a body {error, code}. These are the codes this endpoint gives. Errors and what is charged covers all of them.

Status	Code	When
`400`	`bad_request`	A parameter is missing or wrong. `fields` lists the names. Free.
`401`	`unauthorized`	The `X-Api-Key` header is missing or the key is wrong. Free.
`402`	`credits_exhausted`	The free requests and the balance are used up. Top up in the dashboard. Free.
`403`	`telegram_required`	The account behind the key is not linked to Telegram. The answer has a `link_url` to do it. Free.
`429`	`rate_limited`	More requests in a second than your level allows. Wait for the `Retry-After` header. Free.
`500`	`internal_error`	A fault on our side. Retry shortly. Refunded.
`503`	`upstream_unavailable`	Our side failed or timed out. Retry shortly. Refunded.

FAQ

Questions about this endpoint

How do I search around a point?

Send lat and lng together instead of q. Send q, or the pair, and not both.

How is this different from search/places?

search/places finds places by name only. This also finds the places around a point.

Is the result paged?

No. The places come in one answer, so next_cursor is null and there is no cursor to send.

Your first 100 requests are on us

Get my API key Read the docs