Overview
Typed, versioned actions over a website's own API, such as Yelp business records, search and reviews.
A site integration turns one website into a small, typed API. Each integration offers a few actions, such as
yelp.business, yelp.search and yelp.reviews. You send an action a JSON input, it calls the endpoints the site's
own apps call, and you get back rows in a fixed, documented shape.
curl https://request.usestring.ai/v1/integrations/yelp/business \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "items": ["tonys-pizza-napoletana-san-francisco"] }'The answer is a business record with its address, coordinates, rating, review counts, hours and newest review. You don't have to find Yelp's API, build its requests or parse its responses.
Integrations and /v1/fetch
Every integration runs on Fetch. Each request an action makes goes through /v1/fetch with your
key, so it is unblocked and billed exactly like a request you send yourself. The difference is what
you get back.
POST /v1/fetch | POST /v1/integrations/{site}/{action} | |
|---|---|---|
| You send | A URL, plus method, headers and body | The action's input, such as business ids or a search term |
| You get back | The page or API response, as raw, HTML or Markdown | Rows in the action's published schema |
| Requests per call | One | As many as the action needs, listed in the response |
| Which sites | Any URL | Only the sites in the catalog |
| Response shape | Whatever the site returns | Fixed per version |
Use an integration when the site you need is in the catalog and its actions return the fields you want. Use
/v1/fetch for any other site, for pages an action doesn't cover, or when you need the raw response. You can mix the
two: both use the same key and the same balance.
What an integration guarantees
- Each action publishes a JSON Schema for its input and for its rows. Input that doesn't match is rejected with field-level errors before any request is made.
- An action can only request the hosts its site declares (Yelp's integration reads from
yelp.com), so it can't be used as a general proxy. - When you ask for ten businesses and one can't be read, you get nine rows and one entry in
failures. One bad input doesn't fail the whole call. See Responses & errors. - The response lists each request the action made and the rate it was billed at. See Billing.
- Each site has its own version number, and a change that could break your code is a major version. See Versioning.