> ## Documentation Index
> Fetch the complete documentation index at: https://syncupai-preview-playground-prefills.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Placematch

> Match a place against multiple geospatial data sources using AI-powered entity resolution.
Given information about a place (address, name, coordinates) we will find the right place. Under the hood we use a combination of name similarity, geographic proximity and distance, category alignment, address components
to find candidates and match them with our fine-tuned LLM.



## OpenAPI

````yaml openapi-v2.json post /placematch
openapi: 3.1.0
info:
  title: Reprompt API v2
  version: '2.0'
servers:
  - url: https://reprompt-mikhail--reprompt-fastapi-fastapi-app-dev.modal.run/v2
    description: V2 API server
security: []
tags:
  - name: Enrichments
    description: Use AI to enrich place data with various attributes
  - name: Places
    description: Find, match, and check existence of places
paths:
  /placematch:
    post:
      tags:
        - Places
        - Places
      summary: Placematch
      description: >-
        Match a place against multiple geospatial data sources using AI-powered
        entity resolution.

        Given information about a place (address, name, coordinates) we will
        find the right place. Under the hood we use a combination of name
        similarity, geographic proximity and distance, category alignment,
        address components

        to find candidates and match them with our fine-tuned LLM.
      operationId: placematch_endpoint_placematch_post
      parameters:
        - name: org_slug
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Org Slug
        - name: apiKey
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Apikey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlacematchRequest'
            examples:
              precise_matching:
                summary: Precise matching with name+address+coordinates
                description: >-
                  Most precise matching mode using all available place
                  information
                value:
                  place:
                    name: Starbucks
                    full_address: 1585 Broadway, New York, NY 10036
                    latitude: 40.7614327
                    longitude: -73.9776216
                  match_sources:
                    - reprompt
      responses:
        '200':
          description: Successfully matched places
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacematchResponse'
              examples:
                messy_data_cleaned:
                  summary: Messy data matched to Overture
                  value:
                    results:
                      - name: McDonald's
                        full_address: 1528 Broadway, New York, NY 10036
                        latitude: 40.7589
                        longitude: -73.9851
                        category: fast_food
                        categories:
                          - fast_food
                          - restaurant
                        source: overture
                        is_match: true
                        confidence: HIGH
                        reasoning: >-
                          Good match: normalized name similarity and location
                          within acceptable range
                    metadata:
                      total_results: 1
                      sources_searched:
                        - overture
                      search_radius_meters: 200
        '400':
          description: Invalid input or validation error
          content:
            application/json:
              examples:
                missing_input_error:
                  summary: No input provided
                  value:
                    error: validation_error
                    message: Must provide at least a name OR coordinates
                    details: {}
                incomplete_coordinates_error:
                  summary: Only latitude or longitude provided
                  value:
                    error: validation_error
                    message: Both latitude and longitude must be provided together
                    details: {}
                address_without_name_error:
                  summary: Address provided without name
                  value:
                    error: validation_error
                    message: Address can only be provided together with a name
                    details:
                      suggestion: Include place.name when providing place.address
              schema:
                $ref: '#/components/schemas/PlacematchErrorResponse'
        '422':
          description: Geocoding failed or processing error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacematchErrorResponse'
        '501':
          description: Feature not yet supported (coordinates-only searches, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacematchErrorResponse'
        '502':
          description: External service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacematchErrorResponse'
        '504':
          description: Request timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacematchErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    PlacematchRequest:
      properties:
        place:
          $ref: '#/components/schemas/PlaceInput'
          description: >-
            Place to match. In order to match places you need to provide one of
            the following:


            - **Name + Address**: Provide `place.name` + `place.full_address`

            - **Name + Address + Coordinates (most accurate)**: Provide
            `place.name` + `place.full_address` + `place.latitude` +
            `place.longitude`
        match_sources:
          anyOf:
            - items:
                $ref: '#/components/schemas/PlacematchSource'
              type: array
            - type: 'null'
          title: Match Sources
          description: >-
            Sources to search for matches. Defaults to reprompt if not
            specified.


            Reprompt supports multiple backends for matching against:


            - **Foursquare OS Places** - amazing open data project with 100M+
            global POIs (Apache 2.0 license)

            - **Overture Places** - open map data from the Overture Maps
            Foundation with 64M+ places (CDLA Permissive 2.0)

            - **Our index of places** we picked up from crawling the web
          default:
            - reprompt
        max_matches:
          anyOf:
            - type: integer
              maximum: 5
              minimum: 1
            - type: 'null'
          title: Max Matches
          description: Maximum matches per source
          default: 1
        radius:
          anyOf:
            - type: number
              maximum: 5000
              minimum: 50
            - type: 'null'
          title: Radius
          description: Search radius in meters
          default: 1000
      additionalProperties: false
      type: object
      required:
        - place
      title: PlacematchRequest
      description: Request model for placematch endpoint.
    PlacematchResponse:
      properties:
        results:
          items:
            $ref: '#/components/schemas/PlacematchItem'
          type: array
          title: Results
          description: Array of matched places
        metadata:
          $ref: '#/components/schemas/PlacematchMetadata'
          description: Operation metadata
      type: object
      required:
        - results
        - metadata
      title: PlacematchResponse
      description: Response model for placematch endpoint.
    PlacematchErrorResponse:
      properties:
        error:
          type: string
          title: Error
          description: Error type
        message:
          type: string
          title: Message
          description: Human-readable error message
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: Additional error details
      type: object
      required:
        - error
        - message
      title: PlacematchErrorResponse
      description: Error response for placematch endpoint.
    PlaceInput:
      properties:
        place_id:
          type: string
          title: Place Id
          description: Optional place ID for matching
          default: ''
        name:
          type: string
          title: Name
          description: Name of the place (required)
        full_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Full Address
          description: Address of the place (for more precise matching)
        latitude:
          anyOf:
            - type: number
              maximum: 90
              minimum: -90
            - type: 'null'
          title: Latitude
          description: Latitude coordinate
        longitude:
          anyOf:
            - type: number
              maximum: 180
              minimum: -180
            - type: 'null'
          title: Longitude
          description: Longitude coordinate
        category_primary:
          anyOf:
            - type: string
            - type: 'null'
          title: Category Primary
          description: Primary category of the place
        category_alternates:
          items:
            type: string
          type: array
          title: Category Alternates
          description: Alternate categories of the place
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          description: Phone number of the place
        website:
          anyOf:
            - type: string
            - type: 'null'
          title: Website
          description: Website URL of the place
      additionalProperties: false
      type: object
      required:
        - name
      title: PlaceInput
      description: >-
        Place object input for placematch - supports coordinates-only,
        name-only, or name+address+coordinates.
    PlacematchSource:
      type: string
      enum:
        - reprompt
        - overture
        - foursquare
      title: PlacematchSource
      description: >-
        Supported data sources for place matching and search.


        These sources are available across both the placematch API (for entity
        resolution)

        and the find-places API (for geographic search).
    PlacematchItem:
      properties:
        place_id:
          type: string
          title: Place Id
          description: The ID of the place
        name:
          type: string
          title: Name
          description: The name of the place
        full_address:
          type: string
          title: Full Address
          description: The full address of the place
        latitude:
          type: number
          maximum: 90
          minimum: -90
          title: Latitude
          description: The latitude of the place
        longitude:
          type: number
          maximum: 180
          minimum: -180
          title: Longitude
          description: The longitude of the place
        category_primary:
          type: string
          title: Category Primary
          description: The primary category of the place
        category_alternates:
          items:
            type: string
          type: array
          title: Category Alternates
          description: The alternate categories of the place
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          description: The phone number of the place
        website:
          anyOf:
            - type: string
            - type: 'null'
          title: Website
          description: The website of the place
        operating_status:
          anyOf:
            - type: string
            - type: 'null'
          title: Operating Status
          description: The operating status of the place
        distance_m:
          anyOf:
            - type: number
            - type: 'null'
          title: Distance M
          description: Distance in meters from search point
        source:
          anyOf:
            - $ref: '#/components/schemas/PlacematchSource'
            - type: 'null'
          description: The data source of the place (foursquare, overture, reprompt)
        is_match:
          type: boolean
          title: Is Match
          description: Whether this is considered a confident match
        confidence:
          $ref: '#/components/schemas/ConfidenceLevel'
          description: >-
            Confidence level based on score thresholds: VERY_HIGH (>0.95), HIGH
            (>0.9), MEDIUM (>0.8), LOW (>0.5)
        reasoning:
          anyOf:
            - type: string
            - type: 'null'
          title: Reasoning
          description: Human-readable explanation of the match
      type: object
      required:
        - place_id
        - name
        - full_address
        - latitude
        - longitude
        - category_primary
        - is_match
        - confidence
      title: PlacematchItem
      description: Matched place item - extends FindPlaceItem with matching metadata.
    PlacematchMetadata:
      properties:
        total_results:
          type: integer
          title: Total Results
          description: Total number of results returned
        sources_searched:
          items:
            type: string
          type: array
          title: Sources Searched
          description: Sources that were searched
        search_radius_meters:
          type: number
          title: Search Radius Meters
          description: Search radius used
      type: object
      required:
        - total_results
        - sources_searched
        - search_radius_meters
      title: PlacematchMetadata
    ConfidenceLevel:
      type: string
      enum:
        - VERY_HIGH
        - HIGH
        - MEDIUM
        - LOW
      title: ConfidenceLevel
      description: Confidence levels for place matching.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token in the format: Bearer YOUR_API_KEY'

````