Aisles Inc.

Aisles Inc. Search API

The Search API from Aisles Inc. — 2 operation(s) for search.

GitHub OpenAPI

Operations 2

GET /api/v1/search Find a product at stores near a city or ZIP code #
POST /api/v1/search/batch Up to 10 searches in one request #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/aislesinventory-com/openapi/aislesinventory-com-search-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/aislesinventory-com/json-schema/aislesinventory-com-listing-schema.json
📊
JSONSchema
https://artifacts.apis.io/aislesinventory-com/json-schema/aislesinventory-com-search-result-schema.json
📊
JSONSchema
https://artifacts.apis.io/aislesinventory-com/json-schema/aislesinventory-com-pagination-schema.json

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/aislesinventory-com:aislesinventory-com-search-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

aislesinventory-com-search-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Aislesinventory Com Search API
  version: 1.0.0
  x-api-versioning:
    strategy: url-path
    current: v1
    deprecation_policy: https://aislesinventory.com/api/deprecation-policy
    sunset_header: Sunset (RFC 8594)
    deprecation_header: Deprecation (RFC 9745)
  description: 'Operations tagged Search across 2 of this provider''s published API definitions: aislesinventory-com-openapi.json, aislesinventory-com-sandbox-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://aislesinventory.com
  description: Production (live, read-only)
- url: https://sandbox.aislesinventory.com
  description: 'Sandbox: synthetic test data in the live response shape (also at /sandbox/api/v1/search)'
tags:
- name: Search
paths:
  /api/v1/search:
    get:
      operationId: searchInventory
      security:
      - {}
      - oauth2:
        - read:inventory
      summary: Find a product at stores near a city or ZIP code
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
        description: Product words, e.g. "similac formula", "2% milk gallon".
      - name: city
        in: query
        schema:
          type: string
          enum:
          - chicago
          - new-york
          - los-angeles
          - houston
          - phoenix
          - philadelphia
          - san-antonio
          - san-diego
          - dallas
          - fort-worth
          - charlotte
          - columbus
          - indianapolis
          - seattle
          - south-bend
          - orlando
          - atlanta
          - boston
          - fort-lauderdale
          - baltimore
          - detroit
          - danbury
          - tampa
          - oakland
          - denver
          - las-vegas
          - akron
          - riverside
          - trenton
          - pittsburgh
          - st-louis
          - norfolk
          - milwaukee
          - little-rock
          - tucson
          - west-palm-beach
          - miami
          - aurora
          - louisville
          - minneapolis
          - memphis
          - omaha
          - cincinnati
          - lancaster
          - myrtle-beach
          - austin
          - cypress
          - fredericksburg
          - rogers
          - modesto
          - daytona-beach
          - jacksonville
          - savannah
          - michigan-city
          - kansas-city
          - albuquerque
          - albany
          - buffalo
          - middletown
          - rochester
          - niles
          - tulsa
          - scranton
          - charleston
          - nashville
          - allen
          - el-paso
          - mcallen
          - puyallup
          - birmingham
          - mobile
          - fort-smith
          - camarillo
          - bakersfield
          - fairfield
          - escondido
          - fresno
          - salinas
          - sacramento
          - victorville
          - colorado-springs
          - grand-junction
          - pueblo
          - wilmington
          - hartford
          - fort-myers
          - destin
          - jensen-beach
          - ocala
          - panama-city
          - pensacola
          - sarasota
          - tallahassee
          - commerce
          - columbus-ga
          - augusta
          - coralville
          - davenport
          - sioux-city
          - boise
          - champaign
          - normal
          - rockford
          - springfield
          - evansville
          - fort-wayne
          - kokomo
          - lafayette
          - peoria
          - ashland
          - wichita
          - bowling-green
          - lexington
          - elizabethtown
          - paducah
          - alexandria
          - baton-rouge
          - worcester
          - hyannis
          - hagerstown
          - salisbury
          - flint
          - portage
          - duluth
          - columbia
          - st-cloud
          - springfield-mo
          - jackson
          - tupelo
          - missoula
          - asheville
          - greensboro
          - raleigh
          - fargo
          - wilmington-nc
          - manchester
          - rockaway
          - gallup
          - reno
          - syracuse
          - dayton
          - sandusky
          - st-clairsville
          - toledo
          - oklahoma-city
          - erie
          - allentown
          - columbia-sc
          - greenville
          - florence
          - sioux-falls
          - clarksville
          - knoxville
          - chattanooga
          - abilene
          - beaumont
          - college-station
          - corpus-christi
          - killeen
          - longview
          - laredo
          - lubbock
          - midland
          - san-angelo
          - san-marcos
          - texas-city
          - victoria
          - waco
          - richmond
          - lynchburg
          - roanoke
          - kennewick
          - portland
          - union-gap
          - green-bay
          - johnson-creek
          - madison
          - bridgeport
          - mount-hope
          - vienna
          - huntsville
          - florence-al
          - dothan
          - chico
          - yuba-city
          - palm-desert
          - palmdale
          - fort-collins
          - macon
          - gainesville-ga
          - eugene
          - grand-rapids
        description: Covered metro area. Use city or zip.
      - name: zip
        in: query
        schema:
          type: string
          pattern: ^\d{5}$
        description: 5-digit ZIP code inside a covered area.
      - name: radius
        in: query
        schema:
          type: number
          minimum: 0.1
          maximum: 50
        description: Miles from the city center or ZIP. Leave it out for a city search to cover every store Aisles lists for that city, including malls outside the center; a ZIP or lat/lng search defaults to 10 miles.
      - name: availability
        in: query
        schema:
          type: string
          enum:
          - available
          - out_of_stock
          - unknown
          - any
          default: available
        description: '"available" = in stock or low stock.'
      - name: fulfillment
        in: query
        schema:
          type: string
        description: 'Comma list, all required: curbside_pickup, store_pickup, pickup_today, in_store_shopping, local_delivery, same_day_delivery, ship_to_store.'
      - name: max_price
        in: query
        schema:
          type: number
          minimum: 0
        description: US dollars.
      - name: per_page
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
        description: Listings per page; 10 or fewer keeps responses small.
      - name: cursor
        in: query
        schema:
          type: string
        description: The previous response pagination.next_cursor, for the next page (instead of page).
      responses:
        '200':
          description: Matching store listings, nearest first.
          headers:
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
        '400':
          description: Invalid parameter or location outside the covered areas.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No such address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited; Retry-After gives the seconds to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            Retry-After:
              schema:
                type: integer
        '500':
          description: Server error; retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Busy or being prepared; Retry-After gives the seconds to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Search
    servers:
    - url: https://aislesinventory.com
      description: Production (live, read-only)
    - url: https://sandbox.aislesinventory.com
      description: 'Sandbox: synthetic test data in the live response shape (also at /sandbox/api/v1/search)'
  /api/v1/search/batch:
    post:
      operationId: searchBatch
      summary: Up to 10 searches in one request
      parameters:
      - name: Idempotency-Key
        in: header
        schema:
          type: string
          maxLength: 200
        description: 'Optional. A retry with the same key and body within 24 hours gets the first response again (Idempotent-Replayed: true).'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - queries
              properties:
                queries:
                  type: array
                  minItems: 1
                  maxItems: 10
                  items:
                    type: object
                    required:
                    - q
                    properties:
                      q:
                        type: string
                      city:
                        type: string
                      zip:
                        type: string
                      availability:
                        type: string
                      per_page:
                        type: integer
      responses:
        '200':
          description: One result (or error) per search, in order.
          content:
            application/json:
              schema:
                type: object
                required:
                - results
                properties:
                  api_version:
                    type: string
                  generated_at:
                    type: string
                    format: date-time
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        query:
                          type: object
                          description: The search as sent.
                        pagination:
                          $ref: '#/components/schemas/Pagination'
                        results:
                          type: array
                          items:
                            $ref: '#/components/schemas/Listing'
                        error:
                          $ref: '#/components/schemas/Error/properties/error'
        '400':
          description: No searches, or more than 10.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: The Idempotency-Key was used with a different body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limited (each search counts).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Search
    servers:
    - url: https://aislesinventory.com
      description: Production (live, read-only)
    - url: https://sandbox.aislesinventory.com
      description: 'Sandbox: synthetic test data in the live response shape (also at /sandbox/api/v1/search)'
components:
  schemas:
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              enum:
              - invalid_parameter
              - unknown_location
              - outside_pilot_geography
              - bad_request
              - unauthorized
              - not_found
              - method_not_allowed
              - idempotency_key_reused
              - rate_limited
              - internal_error
              - unavailable
              description: Stable machine-readable code.
            message:
              type: string
              description: What went wrong, in plain words, and how to fix the request.
    Pagination:
      type: object
      properties:
        total:
          type: integer
        page:
          type: integer
        per_page:
          type: integer
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as cursor for the next page; null on the last page.
    SearchResult:
      type: object
      required:
      - pagination
      - results
      properties:
        api_version:
          type: string
        sandbox:
          type: boolean
          description: true on sandbox (synthetic) data
        pagination:
          $ref: '#/components/schemas/Pagination'
        results:
          type: array
          items:
            $ref: '#/components/schemas/Listing'
    Listing:
      type: object
      properties:
        summary:
          type: string
          description: Quotable sentence with retailer, store, status, price and check time.
        retailer:
          type: object
          properties:
            name:
              type: string
        product:
          type: object
          properties:
            brand:
              type: string
            title:
              type: string
            category:
              type: string
        store:
          type: object
          properties:
            name:
              type: string
            address_text:
              type: string
            distance_miles:
              type: number
        offer:
          type: object
          properties:
            availability:
              type: string
              enum:
              - in_stock
              - low_stock
              - out_of_stock
              - unknown
            price:
              type:
              - object
              - 'null'
              properties:
                amount:
                  type: number
                currency:
                  type: string
            last_checked_at:
              type: string
              format: date-time
        links:
          type: object
          properties:
            aisles_offer_url:
              type: string
            purchase_url:
              type:
              - string
              - 'null'
  headers:
    Sunset:
      schema:
        type: string
      description: 'Present only once a removal date is set (RFC 8594): the HTTP-date after which the endpoint stops answering, at least 6 months after Deprecation first appears.'
    Deprecation:
      schema:
        type: string
      description: 'Present only once this endpoint or API version is deprecated: the date it took effect (RFC 9745). Absent on every endpoint today. Policy: https://aislesinventory.com/api/deprecation-policy'
  securitySchemes:
    oauth2:
      type: oauth2
      description: 'Optional agent sign-in (https://aislesinventory.com/auth.md): register at /oauth/register, then client credentials.'
      flows:
        clientCredentials:
          tokenUrl: https://aislesinventory.com/oauth/token
          scopes:
            read:inventory: Search store stock
            read:answers: Read the ready answers per city
externalDocs:
  description: Versioning and deprecation policy (Deprecation and Sunset headers before any version stops)
  url: https://aislesinventory.com/api/deprecation-policy
x-refined-from:
- aislesinventory-com-openapi.json
- aislesinventory-com-sandbox-openapi.json
x-sandbox:
  url: https://sandbox.aislesinventory.com
  openapi: https://sandbox.aislesinventory.com/openapi.json
  docs: https://aislesinventory.com/sandbox
  auth_required: false
  synthetic_data: true